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The Smalltalk 0.3 Pre-Beta Release 
June 12, 1986 


We are sending you a copy of this pre-beta release for several reasons. We 
know that some Universities may want to teach Smalltalk in their fall 86 
classes. This pre-release will give them some idea of the version they 
will have available to teach with. We are also Interested in getting 
feedback about bugs. The final 0.3 release of Smalltalk will be available 
in August. l 


Quick Overview of Some of the Naw Features In this Release 


1.Window update is much faster since bitmaps of underlying windows are 
saved. This makes the whole system much faster and more usable. This 
new scheme takes up more space. If the system is about to run out of 
space, It will turn off the fast window feature then tell you you are low 
on space. If you later want to turn on the fast window feature again just 
choose fast windows from the screen menu. 

2.The screen is now properly updated at all times. 

3.The window menu, which is accessed by pressing down on the mouse 
while over a window title tab, is now optionally accessed using the 
command key with the mouse instead of the Enter key as on the 0.2 
release. 

4.You can now run Smalltalk from inside a folder using the new HFS file 
system. The image file and changes file should be in the folder you start 
Smalltalk from. The Smalitalk-80.sources file can either be in that 
folder or in the main folder of the same volume. Once Smalltalk is up 
and running, you can access any folder on any disk. You do this by using 
the choose volume menu in a file list window. The choose volume menu 
shows you all the folders in a volume or folder that you choose. To 
select a particular volume or folder, choose it twice in a row. The file 
list itself contains a list of the files inside the folder you choose. You 
can type in a subset command in the top pane to select a subset of the 
files within the chosen folder. 

5.If you look at the menus of a browser, you will notice some new entries. 
The most useful one is versions. Versions allows you to open a window 
on a list of the current version of a method, at the top, as well as all 
previous versions that are stili in the changes file. If you change a 
method then want to put It back the way It was before, use versions to 
do this. You will also notice that you can now rename method categories, 
classes and system categories from a menu. Rearranging or removing 
system categories and method categories Is also easier now. 

6.When you file out a System Category or Class, you now have the option. of 
filing out any Shared Pools used by that part of the system. 

7.There are many other nice improvements to the system that make it 


faster and easier to use. Most of these will be obvious as you use the 
system. We have also fixed a lot of bugs. 

8.There are a lot of new editor features that are described in a separate 
enclosed memo. 

9.This release is supposed to be able to run with the Ram Cache enabled as 
long as you leave enough space for Smalltalk. If there is a problem 
running with the ram cache, turn it off before running Smalltalk. 

10.We are sending this to you because we want feedback about bugs and 
feature problems. Please send your bug reports, comments, etc to: 


The Smalltalk Group 
Apple Computer 
20525 Mariani Dr 
Cupertino, CA. 95014 
Mail Stop 22-Y 


w to Install this Rel 


Disk1 contains: 
1.June11.image 
Disk2 contains: 
2.Junet1.image 
2.June11.changes 
Disk3 contains: 
1.June11.changes 
Disk4 contains: 
June 1.interp 
DivJoin 
Join 
NewDivJoin 
new Goodies 


The diskettes on this pre-release contain all the files you need except 
Smalitalk-80.sources and the goodies folder. We are assuming you still 
have the 0.2 Smalltalk release and can use the Smalltalk-80.sources file 
from that release. The goodies from that release should still work with 
this release but we have not tested them all completely. The rs232 goodie 
and the printing goodie have been modified for this release so you should 
use the Included new versions of those goodies. You can use DivJoin to 
join 1.Junett.image and 2.Junet1.image. Also use it to join 
1.June11.changes and 2.Junet1.changes. Using DivJoin is described In the 
0.2 release notes. We included Join and NewDivJoin as alternatives to 
DivJoin. These new utilities offer new features that DivJoin doesn't have 


but Join and NewDivJoin have not been heavily tested. Instructions for 
using these are included below. 


Always use the Junet1.image and changes with the Junet1 interpreter. It 
will not work correctly with the 0.2 interpreter. Versions of 0.2 images 
should work with the June11 Interpreter but we have not tested that 
combination heavily. - 








DivJoin and all its many flavors... 


Several programs to divide and rejoin large files are included on Disk 4. These are necessary 
because the image and changes files are bigger than 400k. DIVJOIN, JOIN, and NewDivJoin are 
all included, despite some overlapping functionality, because each works a little differently, and 
has some weaknesses. Use whichever version you're most comfortable with... and we'll try to 
ship just one version next time. 


NewDivJoin 


in general, NewDivJoin is the easiest and most flexible to use. Unfortunately, it is just that 
(New), and may be less reliable than DIVJOIN and JOIN. Unlike DIVJOIN and JOIN, NewDivJoin 
allows you to go directly to and from multiple floppies. 


` Whether you choose Divide or Join, you're presented with a Standard File dialog for selecting the 
composite file, or the first piece of a divided file you're joining. The file lists presented by 
SFGetFile are often empty, because files that are inappropriate to the selected operation are 
filtered out. Only files large enough to need dividing or named appropriately for join (pieces 
starting with "1.") are shown. 


To Join: 


- Click Join, then use SFGetFile to Open the first piece of the file you're joining. 

- Use SFPutFile to name the output file, select the destination disk, and click Save. 

- Insert disks with succeeding pieces of the file, as prompted, until there are no more. 
- Click Done when prompted for a new disk and there are no more pieces to the file. 


Make sure to select the right destination disk. NewDivJoin defaults to the same disk as the first 
piece of the file, which is of course already full. If you try to put the joined file there, the join 
fails, and your disk becomes, annoyingly but harmiessly, too full to build a desktop file for when 
you insert it later. 


To Divide: 


Use the radio buttons to choose single or double-sided disks for dividing the file. 
Click Divide, then use SFGetFile to Open the file you're dividing. 
Insert disks as prompted for succeeding pieces of the file. 


Divide tries to be considerate about the disks you insert, and how it formats them. If you insert 

a readable Mac disk that has files on it, or a non-Mac disx, or a damaged one, you'll get an alen, 
and have a chance to reconsider. The only mistake it cannot detect is insertion of an double sided 
disk in a single sided drive. Also, if the disk is already formatted with the appropriate number 

of sides, NewDivJoin skips reformatting it to save time. ) 


When the divide or join operation is done, you'll get a note alert saying it was completed 
(success!) or stopped (you cancelled, or there was an error). NewDivJoin has been observed to 
hang on an XL with old roms, and its error messages are sometimes incomplete. Suggestions are 
welcome. 





Ihe Join Program and using it with Smalltalk 


Here we describe version 1.0D1 of the Join program. 


Purpose o! the Join Program 

The Join program does the same thing as the join hat of DivJoin. (DivJoin has been distributed with the 
Smalltalk release and the Software Supplement). DivJoin has the limitation that 4 requires the Input files 
and the output file to be on the same volume (and in the same folder on HFS). This could be a problem for 
people on the Macintosh Pius since they can run the full level 1 Smalltalk, but have no way of creating the 
larger image file, unless they have access to a hard disk. The Join program solves this problem. tt also 
gives the user a Standard File dialog for naming the output file. The Join program does not replace the 
DivJoin program, because it does not divide files. It will join the files divided by DivJoin. 


Using Join 
The divided files must be given the names °1.foo", “2.f00”, etc.; these are the names assigned by the 


DivJoin program. All the pieces must be in the same folder (for MFS volumes, on the same volume). You 
use the Join program in one of two ways. 


First, you can open the application by Itsell. You will see a Standard File dialog that lists only files whose 
names begin with “1."; these files are the first pieces of divided files. You just open the file you want to 
join; clicking Cancel will return you to the Finder. 


Second, you can select any piece of 1 or more divided files along with the Join program, and open them all 
at once. The program will join each of the files and exit to the Finder. With this mechanism, you can select 
any piece of the file (ie. “2.foo”} not just the first piece. But you should not select more than 1 piece (ie., 
"1.00" and “2.f00"), because Join will try to join the file twice. 


in some cases, you might see a message saying the file cannot be joined. This can happen if the program 
cannot open the first part of the file, the file does not follow the naming conventions, or the program 
cannot create the output file. {in some cases, the problem might be that the input file was left open by 
another program; rebooting and trying again might fix the problem.) 


For each file that is to be Joined, you will get a Standard File dialog in which you specify the output file. The 
default will be the name minus its prefix (ie. 100”) on the same volume/folder as the original. You can 


change this as necessary; you can even eject the diskette containing the input pieces (if you have only 1 
disk drive). 


When you confirm the dialog, the program begins joining. You will see a dialog indicating the current piece 
being read. (The number in the corner Indicates the size of the VO butfer.) You can cancel the join by 
Clicking the Cancel button. You should see a message indicating that the join was completed, was 
stopped, or that an VO error occurred. The program will fill ts entire. buffer, even if it means reading several 
pieces of the file. (This means that on a Mac+, join can read the entire Smalitalk image into memory from 
the divided files on one diskette then write Itas one joined file onto another diskette.) 


You should be able to use Join to Create a Smalltalk June11.image and 

Juneit.changes without a Hard Disk ' 

Put the June11.changes and a Small system folder on one 800k disk and call t Changes. Put 
dune11.image and Junet1.interp and a second 800k disk and call it image. Boot with Changes, eject it 
and insert image. Double cick on image to start Smalitak and the system will prompt you to put in disks 
until you end up in smalitak with the Changes disk in the drive. We have not had time to test this 
procedure with this release. There is a chance R may not work here since the changes file is very large. We 
left the changes file large for this release so you could use your old sources file. On the final 0.3 release, 
the changes file will be vary small and you will defintely be able to run Smaftakk on a Mac Plus using without 
a hard disk. Without the hard disk though, It ls not easy to browse sources. There is a goodie that allows 
you to do t by Interchanging diskettes. There is also a way to have one sources file on a common Hard 
disk that ls shared by many Macs running Smalitalk and browsing that sources file using Appletalk. That will 
be described In more detali in the real 0.3 versions release notes. 


New EDITOR FEATURES 


Miscellany 


When the selection is a caret, the cut and copy commands are no-ops’. They just 
flash at you, and they don't change the paste buffer. These and most other no-ops do 
not lock the model, so you don't have to cance! them H that's all you did. 


When the selection is not a caret, the copy, copy & undo, and copy & again 
command sequences change the paste buffer but do not lock the model. 


Ctri-V (paste) may be typed ahead without flushing previously typed characters. This 
is useful when you want to type a few characters before pasting something, or when 
you want to paste the same text at several places in a statement. The paste and the 
typing on elther side of it are separate commands for the purpose of undo. 


Ctri-' or Ctrl-~ serve as "ESC" key substitutes. They select the last typeln, paste text, 
etc. 


Ctri-_ does what Ctri-( does In other Smalitalks: i [un]parenthesizes the selection. On 
the Mac, all Ctr-Shifi-digits are reserved for the operating system. 


Before, H you typed something and then, before all the typeahead was gobbled, you 
clicked the mouse, the editor gave priority to the mouse, made a new selection, and 
inserted the typeahead there. Now It gives priority to the typeahead, so Ht appears in 
the right place most of the time. 


I made a few esthetic cleanups, some of which help performance, and none of which 
hurt. The scroll bar marker (elevator) no longer blinks after every edit and burst of 
typing. Typing and backspacing now adjust the scroll-bar marker (elevator) H 

_ necessary. l 


Outside the ParagraphEditor, In related classes, | made some other improvements, 
0.9. : 


If you try to invoke format (without the shift key down) when you have already made 
some edits to a method, the view flashes. You should accept or cancel before trying 
again. (it used to format the original text, causing your edits to vanish.) 


The TextConstants pool now Includes variables for all fifty-two ctri-letters, 1.e., 


SOS ctrlA..ctriz. it no longer includes variables named Cut, Cut2, Copy, and 
aste. i 


If you select a method in the fist pane of a messaga-list window {e.g., "Senders of 
to:by:*) it will automatically find the first occurrence of the first keyword in the last token 
of the window label (8.g., *to:*). To find another occurrence, use copy and again. 


Undo 


The undo command has been overhauled. It has more Macintosh-Bke’ behavior, Le., K 
resiores the paragraph and the selection to thelr condition immediately preceding 
execution of the last command that changed the paragraph. 


Undo and redo work correctly for ried conero; and they work even N you have 
moved the selection. Because of the latter feature, you can no longer use undo as e 
form of paste (Exception: when-you are in a different paragraph than the one that did 
the original command, and there is no other way to get back the undo buffer, It lets you 
get k back with undo.) 


Undoing a cut or copy restores the paste buffer to its prior contents. Thus, H you cut 
and then accidentally copy instead of paste, you can undo the copy and then 
complete the peste. : 


Any series of typing and backspacing keys, however mixed, is a single command. 
Undo restores everything they deleted, and redo undoes undo perfectly. 


Undoing or redoing a cancel faithfully restores the earlier state. (in transit to that 
earlier state, there is excessive screen activity that | hope does not annoy you too 
much.) 


Many more no-ops (besides scrolling, selecting, accept, and dolt) are now 


transparent to undo; that Is, the previous command can still be undone and redone. 
These Include: 


* leaving the pane and retuming without executing commands In other paragraph 
editore 


| *cuUcopy of a caret 
e again when nothing was found 


H you undo a shift-agaln, the paragraph and selection are restored to their exact prior 
. Slate, and you can redo. But unshiftec-egain Is treated as a special case to allow 
selective substitution: ts undo will restore the search text in the one place It was 
changed and leave it highlighted: redo will replace 8 again by the change text; and no 
matter what you do, another again. will search for the original search text. Note: The 


again command, unlike Its undoer, always starts each search at the end of the current 
selection. 


Again 


The again command has been overhauled. R used to repeal the last copy, paste, or 
overtype command at the next occurrence of the same original text. Now i can repeat 
other commands that replace text, in particular, cut 

*Againing” no longer has any effect-on the paste buffer. Therefore, H you do: some 
typing and then again, and then decide you want the paste buffer to have the selected 
text, do a copy at that point. (This change is consistent with the ability to repeat a cut,. 
but | am not certain It wil be liked. Try it for a week or so and let me know.) 


k used to be that you couldn’ use again after typein If you had backspaced to make a 
correction. This has been fixed. if you backspace past the original selection, the 
backspaced-over characiers will all be included In the search string. 

An again repeats the last replacement in any ParagraphEditor, not Just the one 
currently active. (It uses class variables FindText and ChangeText to remember Hs 

‘. parameters.) - 


py. In the past, if you wanted to search for something, you had to see an 
example of it, select the example, invoke copy, and Invoke again. Now, H you can 
not see an example of the search key, you can place the caret anywhere, type the 
. search key, and invoke again. The example will be deleted and the search will 
commences. Note: The typing and deletion of the search key do not lock the model; if 
you made no other edit to the paragraph, you need not cancel It. 
Find same text. If the last command was an again (or undo again), the same find 
and change strings are used as last time. [In the past, Hf you found an occurrence with 
again and then did some editing, you lost the ability to search for the next occurrence. 


Now, the ctri-S (Same) command continues the most recent again, rather than 
repeating an intervening edit. 


New Commands 


The following contro! keys are now defined (the shift key is Ignored for all ctrl keys): 
ctri-2 Undo (same ettect as the menu command, undo) 
ctr-P  Printit (no need to select type-in first) 
cti-O Dot (no need to select type-in first) 
cirl-S Same (repeat most recent again) 
A-R Right shift (indent selected fines) 
cir-L Left shit (outdent selected lines) 
ctr-D Duplicate (copy the selection, and paste It over the prior selection) 
cir-E Exchange/Move (exchange the current selection with the prior selection) 
ctr-Q Query symbol table (complete the symbol preceding the caret) 
cîr-A Advance (place the caret after the next token) 


None of these comes avaliable in a menu, but H you add exchange yourse? to your 
yellowBupMenu, ft will work correctly. Each new command ls described In Its own 
section below, except the first three, which are equivalent to menu commands. 


ciri-S (Search) 


N you have done an again and then some editing, and then want to search for more 
occurrences of the same search text in any window, use ctr+S. k starts the search after 
the selection. H It finds another occurrence, It highlights k but does not change R. 
Otherwise, N flashes. In either case, it ls a no-op for the purposes of undoing and It 
doesn't lock the model. H you want to °un-search’, undo twice after It. 


etri-R and etri-L (indent and Outdent) 


These commands ere similar to the corresponding ones in the Lisa Mouse Editor. 


Terminology. 


A Ene stens after a carriage return (or at the beginning of the paragraph) and ends 
with a carriage retum (or at the end of the paragraph). 


A subject Ene is a line in which at least one character Is highlighted. 
A non-blank Ene ls a subject line with at least one visible character. 
When a ine does not start with a tab, to delete the leading tab is & no-op. 


| Operation of etr-R (indent). 


H the selection Is a caret, insert a tab at the left of the fine containing the caret, thereby 
moving the caret one indent-level to the right 


H the selection Is not a caret, insert a tab at the lef of every non-blank Ene. After 
indenting, the same text is selected as was selected before. 


` 


Operation of ctri-L (Outdent). 


if the selection ls a caret, delete the leading tab from the Ene it is on, thereby moving 
the caret one indent-level to the left, unless it is already flush left. 


H the selection Is not a caret, delete the leading tab from every subject ine. After 
ouidenting, the same text is selected as was selected before. Exception: { any non- 
blank ine lacks a leading tab, then flash the view and do not make any changes to the 


paragraph. 
Using ctr-R and ctr-L 


Typing several of these characters ahead indents several levels In a single atomic 
step. For example, typing ctri-R, ctrt-R, ctr-L is the same as typing just one cin-R. 


You can Indent or outdent the Enes containing a [block] by double-clicking Inside a 
bracket and then typing ctr-R or ctri-L. 


etrl:D (Duplicate) and ctri-E (Exchange/Move) 


Terminology. i : 


When a selection is made by a click, double-click, dragging, or shift-dragging, a check 
le made to see whether the selection that existed before in the same paragraph was 
disjoint from the ne selection. H so, ftis remembered as the prior selection. To be 
considered disjoint from the new selection, a caret may not touch elther end of the new 
selection, and- may not lie within it. A prior non-caret may touch one end of the new 
selection, but may not overlap It. (A new class variable, Undointerval, ls used to assist 
in this determination.) 


Operation of ctri-D (Duplicate). 


This is similar to the following sequence of commands: copy the current selection; 
paola it over the prior selection. However, the paste buffer is unaffected. The caret is 

fi after the duplicated characters, 1.a., in the nelghborhood of the prior selection. H 
you want the duplicated text highlighted, usa ctr. 


Use this command when you are typing andiyou want to avoid retyping something that 
ls lengthy or hard to spell. Simply select the text you want to duplicate, type ctri-D, and 
continue on typing. It is also useful! in building your temporary-variable declaration. 


Operation of ctri-E (Exchange/Move). 


When neither operand is a caret, exchange the current selection with the prior 
selection. Whatever text was selected before the exchange Is still selected afterwards, © 
. but in its new location (where the prior selection started out). Another ctr-E is the 
same as an undo. 


Either operand, but not both, may be a caret. In that case, move the non-caret to the 
caret, and leave a caret after the moved text. If you want the moved text highlighted, 
usa cirl-~. if you leave it a caret, another cirl-E is not the same as an undo; 8 flashes 
and does nothing. - i 


One of the many uses for this command is to exchange the true and false branches of 
a conditional. Double click inside a bracket of one branch, then inside a bracket of the 
other branch, and type ctrl-E. Other common exchanges are: two arguments of a 
message, the left and sight sides of a simple assignment, and two statements. 


The move version of ctri-E is used in the same situations as ctri-D, but when you want 
the selected text to be moved instead of copied. i use it to reorganize class protocols. 


i don't want to hear any Jokes about modes. 


The ctri-Q (Query Symbol Table) Command 


When you type ctrl-Q, the selection mus! be a caret, and an identifier must precede Ht. 
That Kentifier is called the Aint. Smattalk will find e symbol that matches the hint (as 
explained below), and will replace the hint by what k found, the offering. R will then put 
& space after the ey and place the caret after thai space. For example, H you type 
‘dese! and then ctr-Q, Smalitalk displays: 


deselect: 4 


Exception: H the offering is a multi-keyword selector, two spaces will be inserted 
between each pair of keywords, and the caret will be placed after the first keyword, 
allowing you to type in the first argument without touching the mouse. For example, If 
you type ‘detec’ followed by ctri-Q, Smalltalk displays: 


detect: , None: 
Use cir-A (described below) to skip to the next argument. 


H the offering is not the one you wanted, type ctri-O again immediately. (The previous 
offering musi stili be displayed, and no editing may have intervened.) Smalhalk will 
search for another offering and replace the first one by H as above. For example, H you 
type another ctri-Q after seelng: 


detect: a None: 
Smaltalk displays: 
detect: , 


When there are no further matches, ctri-Q will restore the text to the way It was before 
` the first ctr-Q, and flash the view. 


H you undo when an offering is present and no further editing has ensued, the original 
text will be restored. After a redo, you can continue the search. 


Hf you type ctri-Q and then click the mouse elsewhere In the paragraph, the editor tries 
to guess what you meant, as follows. If there is an offering displayed, another cir-Q 
will restore the selection and continue the search with the same hint. But if only the 
original hint is displayed, the identifier before the new position of the caret becomes a 
new hint and a new search commences. 


At the moment, only symbols that could be selectors and that begin with a lower-case 
letter are offered. This command could be generalized to look for global variable-like 
names when the first character is upper case, but | haven't done that yet. 


A ctr-Q queries the Symbol table, not the method dictionaries. The case of characters 
in the hint does not matter. However, spelling counts. 


Using cif-Q. 


Use this command when you cant remember the spelling or capitalization of a long 
message selector, or when you cant remember all its keywords, or when you just dor” 
want to type a lot. Ifind it particularly useful for long messages to the ' Mac’ object, 
esp. H1 have taken the trouble to get thelr true keywords into the Symbol table instead 
of a lot of ‘with’s. Also use t when you are inventing a new message name and you 
want to be sure Ht is new, or, SENTO H you want to try to pick a name that has been 
used before. 


Type as many characters of the name as you can remember, and then type cirl-Q. 
Usually, you will type the first keyword, Including the colon, but if you wish, you may 
type fewer or more characters. All the following will complete to detect:IfNone: {in 
my image): 


detect: 
det 
detect.ifn 


The more you type, the more you will remove ambiguity and the fewer spurious 
answers you will see. If you find yourself working through a long list of matches, 
invoke undo (with etri-Z if you like), add a few more characters to the identifier, and 
type cirl-Q again. 


The ctri-A (Advance) Command 


When you type cirl-A, the caret is placed after the next token following the selection. 
- The effect is exactly as if you had clicked there with the mouse button. 


Usage: When you use ctri-Q to complete a multi-keyword selector, type the first 
argument, then use ctri-A to advance to successive argument positions. For example, 
after ctri-O gives you: 


detect: , None: 


Type the first argument and then use ctri-A to obtain: 
detect: firstArgYouTyped HNone: ary 
When you use ctri-_ at a caret to obtain a pair of parentheses, type the expression to 


be. parenthesized and then use ctri-A to skip the right parenthesis before you keep 
typing. 


Implementation Notes 


Peeudo-instance Variables. 


The variables Undolnterval and Priorlinterva! are logically instance variables.. | made 
them class variables so that the editor could be filed into an active image with open 
windows and used without further ado. When an editor terminates control, I stashes 
the values of the two pseudo-Instance variables In the rea! instance variable 
beginTypelnBiock, which is always nil at that point. When the editor regains control, k 
restores the values to the class variables and sets beginTypeinBiock back to nil. | 
have made this robust; but It is still wrong, and should be fixed H we ever put this editor 
into an official release. . 


Undo. 


To implement undo the Macintosh way, | borrowed some ideas from MacApp. Every 
command leaves behind an object that knows how to undo that command. Rather 
than declare lots of command classes as in MacApp, I just use a set of class variabies 
in class ParagraphEditor: UndoMessage, UndoParagraph, Undolnterval, and Undone. 


These variables are not accessed directly by code you writs. To set their values, call 
the method self undoer:with:forRedo: (using 0, 1, or 2 with:s), or call a higher- 
leve! method like replaceSelectionWith:. To fetch their values, use the techniques 
described below. 


UndoMessage is a Message whose selector is known as the undoer and whose 
arguments are known as the undo parameters. The undoer is the selector-symbol of e 
message to a ParagraphEditor instance that will undo one or more kinds of 
commands, and the undo parameters are the arguments you want passed to that 
method. For example, the cut and copy commands make the undoer be 
fundoCutCopy:, and make its one parameter be the previous paste bufier. 


UndoParagraph ls the paragraph In which the last edit occurred. If you try to undo en 
edit in one paragraph that occurred in another, the editor places the caret at the 
beginning of the paragraph and inserts the saved text there. This variable Is not 
meaningful during execution of an Undoer method. 


Undointerval is the range of characters that the last command caused to appear and 
that should disappear if the last command is undone in the same paragraph. For 
example, for typing, It includes all the typed characters, not just the caret. The undo 
command selects Undolnterva! and blinks k briefly before invoking the appropriate 
Undoer. That is why you can move the selection and still have undo restore the state 
of the paragraph correctly. Note: The "select last" command (ESC, etr-~, ctr’) actually 
selects Undointerval. 


Undone helps keep track of the do/undo/redo phase for the benefit of methods that are 
used in more than one phase. Rs value ls set to the last argument of 

self undoer:with:forRedo:. You can find out what phase you are In now with self 
isDoing-IsUndolng-IsRedoing, only one of which is true at a time. 


Sometimes these class variables are examined In doers. For example, init” 
Interested in whether the preceding command was an again, a copy, oree ro > 
else. it finds out by testing UndoMessage selector == fundoAgaina: nti! 
method (completeSymbol) is used asa doer and redoerbut not as fini... 
needs to know whether Rls executing an Initial ctr-Q, a repeated ct-O, e». 
determine Rs action, Il tests UndoMessage, UndoParagraph, and Unde: 


| ‘The standard undoer methods are: 

eundoReplace i 
Used by: align, emphasis-change, format, ete. 
dust swaps undoSelection and the contents ef undointerval 

* undoAndReselect: undoHighlight redoAndReselect: redoHigh. i: 
Used by: type!n, paste, cancel, printit, ete. 


Like undoReplace, but highlights something other than the whole «=< - 
after an undo and/or redo; the Intervals highlighted are undoHig > 
redoHighlight. ; a 


eundoCutCopy: oldPasteBuffer 

Usad by: cut and copy 

Like undoRepiace, but also restores the paste butter. 
*undoAgain: Indices andReselect: home 

‘Used by: again, shift-again, Same (ctr-S) 

Undoes or redoes the replacement at the specified character Inc 
eundoQuery: hintText lastOffering: selectorOrNil 

Used by: ctr-Q co n 

Unde restores the origina! hint, redo resumes the search where It è 


Some commands serve as thelr own undoers and/or redoers. For examp 
done and redone by the same method (completeSymbol). Ctri-E use: © - 
method for all three phases of its command: i 


*eichangeWith: otherinterval 
Used by: ctr.E {exchange/move) 
When doing: exchange the prior selection with the current selec’ + 


When undoing or redoing: exchange the text in the UndoParame:... 
with the text in the Undointerval. 
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-menu commandi: 
ee? geltieloseTypeln: . ~ 
= .. Do your stuff, usually to the text self selection In self selectionintervar 
*Make changes to the paragraph and set up for undo: see below” 
"if you don't want to leave the entire replacement highlighted,call a selecting- 
method here, @.g., selectAt: or selectFrom:to:, otherwise just call? 
To make changes to the paragraph and set up for undo, the most general technique Is: 
UndoSelection «- oldText. 
self zapSelectionWith: newText. 
la pe BOM undoer: gundoMe with: parami with: param2 forRedo: false. 
-`+ The above message. sets Undolnterval to the current selection. H this is not 
what you want, now is the time to change It* Ra 
H all you need is a simple undoReplace, a simpler technique is avallable: 
self replaceSelectionWith: newText. 


N you want the selection after undo and/or redo to be other than the whole 
replacement, use the undoer undoAndReselect:redoAndReselect:, obtained 
most simply by: 


self replace: oldinterval with: newText and: [self selectAt: Index] 


The ritual for a keyboard command Is the same, but your method is called with an 
argument, characterStream (the typeahead buffer). The method must return false i 
h does typing and/or backspacing, but true if It terminates the previous typeln. To 
terminate'typeln, instead of closeTypeln, call closeTypeln: characterStream to 
save the typeahead, N.B.: You absolutely must call sensor keyboard to fiush your 
character from the queue. | 


The ritual for an undoer ls simpler. There is no need to closeTypeln. The selection 
ls already restored to Undointerval and has blinked If necessary. H undoing and 
redoing are not identical, make self isUndolng the last argument of 
undoer:with:forRedo: instead of false. 


in all command routines, the selection is already unhighlighted upon entry. Upon exit, 
the selection is automatically highlighted and scrolled Into view, and the scroll bar 
marker is automatically updated if necessary. 


To define.your own commands, imitate others that are Uke R. The general ritual for & 
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Preface 


About this Release 


Following the enthusiastic response for our August 1985 release of Smalltalk among 
universities and other users, we have put together this Macintosh Plus release of the 
Smalltalk-80 programming system. (Users who have only a Macintosh 512K or a 
Macintosh XL can still run the August 1985 version.) The Mac Plus release is also 
intended for members of the new Apple Programmer's Club, which we hope will aid the 
spread of information and tools to others besides Apple Certified Developers. We hope 
that this new release will enable more hands-on experience with Smalltalk by universities 
and other interested parties. 


This release supplants the earlier August 1985 release (version 0.2). 


Features which carry over from the August 1985 version are: 

¢ Improved volume management capable of supporting file server access 

* Automatic spelling correction for variable and message names 

* Ability to handle multiple images on the same disk 

* A single interpreter works on all machines and expands to use extra memory 

e Total object capacity is 32K 

* Able to run on some Macintosh computers with 1MB or more of memory 
(available from various manufacturers, but must be contiguous 
and must follow ToolBox memory organization) 


Completely new features for the Macintosh Plus version are: 
e More complete Macintosh Toolbox access. 
° Faster painting and repainting of views and text. 
e New and better Editor features. 
* Hierarchial File System support. 
* Menus are compatible with Xerox Version II of Smalltalk-80. 
e Pascal Record compatiblity to enhance Toolbox calls. 
* Miscellaneous extensions to the Smalltalk language. 


Although Smalltalk-80 runs as an interpreted language, and native code generation is not 
yet available, the Macintosh Plus version can serve as a useful environment in which to 
build prototypes of simple systems. The turn-around time is extremely rapid, measured in 
seconds, allowing much faster development than with standard compiled languages. 


Documentation and Support 


We hope that this manual will provide you with enough documentation to get you started. 
To work most effectively with the Smalitalk-80 system, you will need further 
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documentation not provided by Apple, such as the two Smalltalk-80 books by Goldberg 
and Robson (see Bibliography). 


Also, courses and training materials that relate to Smalltalk-80 are available from PPI, an 
organization that offers general training in object-oriented programming as well as specific 
courses on Smalitalk-80. For further information, contact: 


Productivity Products International 
27 Glen Road 

Sandy Hook, CT 0648 

(203) 426-1875 : 


Apple cannot provide support for this pre-product release, since we are charging only 
enough to cover our costs of duplication and handling. If you should discover bugs in the 
documentation or in the system itself, your only recourse will be to work around them 
yourself. (Of course we would be happy to hear from you about bugs. See the address 
below.) 


If we later release another version of Smalltalk, there will be neither an upgrade price nor a 
guaranteed code migration path. 


The Apple Smalltalk Newsletter 


We want to know what you find to be good or bad about the system as released. We are 
especially interested in specific improvements or extensions which you find amusing or 
useful, or in any training materials whick you may develop. Assuming there is sufficient 
response, we shall assemble such contributions in a newsletter for those who have 
purchased this release. i 


Since we do not have time to maintain an ongoing newsletter, we hereby solicit offers to 
take over publication of the newsletter following our first free issue. Assuming we find a 
volunteer to take over the newsletter, we will make the new arrangement known in the pilot 
issue. 


Please send your comments and contributions to the address below: 
The Smalltalk Group, Mail Stop 22-Y 
Apple Computer 
20525 Mariani Drive 
Cupertino, CA 95014 
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The Future of Smalltalk at Apple 


This Macintosh Plus release is only the latest of several non-supported versions of 
Smalltalk-80 that have been released by Apple. You will notice that this release violates 
Macintosh standards of user interface design in many ways. Windows do not repaint 
automatically, and mouse clicks may be lost. These are characteristics of the Smalltaik-80 
system as originally licensed, and we have not tried to fix them for this early release. 


One of the reasons why we will not support this release is that we are contemplating 
substantial changes to the system with the goal of completely integrating Smalltalk with the 
Macintosh user interface and ToolBox. The result will be a Smalltalk system that is 
smaller, faster, and more compatible with other Macintosh software. 


Note that the present release allows toolbox calls, although the integration is not complete. 
For example, when you compare the effect of executing 

Pen new mandala: 30 diameter: 360 
which draws lines without the aid of the ToolBox, with that of 

QDPen new mandala: 30 diameter: 360 
you will see why we are excited about the combination of Smalltalk's flexibility with the 
speed of the Macintosh Toolbox. 


In spite of the changes which we anticipate, we plan to stick with the language syntax, 
semantics, fileOut formats, and general programming interface embodied in this release of 
the Smalltalk-80 system. 


We can make no guarantees, but we are contemplating even more exciting 
developments in future releases of Smalltalk from Apple. One possibility is complete 
integration with Apple's MacApp (a generic application), Object Pascal, and Objective "C". 
This would allow developers to program clickable applications in Smalltalk, and at the 
same time take advantage of existing code in Pascal or "C". 
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How to Use this Manual 


This Manual might be your first exposure to Smalltalk. Of course, we recommend you 
read the very good references listed in the Bibliography, but you could make a start 
understanding the system and writing programs if you make use of the material in this 
book. The following diagram shows the breakdown of the chapters and appendices. 
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Appendices 


The first two chapters will introduce you to Smalltalk-80 and give the installation procedure 
to get you started. It will be much easier to appreciate Smalltalk if you try it out on a 
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working system. Chapter 3 introduces the user interface of the Smailtalk-80 system, 
allowing you to explore the system immediately. Chapter 4 contains a great deal of 
conceptual material, but provides a start in understanding the Smalltalk-80 language until 
you consult the other references. 


Chapter 5 discusses many important features of the User Interface and Environment that 
won't make much sense before reading Chapter 4. Chapter 7 discusses Macintosh- 
specific issues of interest to programmers who want to make use of the Macintosh Toolbox 
and to operate within the Hierarchial File System of the Macintosh Plus. 


The Bibliography contains a complete list of Smalltalk references, and the Glossary defines 


most of the most important terminology. Finally, there are several Appendices providing 
detailed technical information for the serious programmer. 
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Chapter 1 


Welcome to 
Smalltalk-80 


Overview: 


Smalltalk-80 is a graphics-based, interactive, programming- environment. From its 
beginnings in the early 1970's at the research laboratories of Xerox Corporation, Smalltalk 
has had a tremendous influence on modern computer systems. In fact, the design of 
Apple's Lisa and Macintosh computers was directly inspired by Smalltalk. The "-80" 
suffix indicates the most recent standard version of Smalltalk, the result of several 
evolutionary steps since the beginning. Smalltalk-80 is available on a variety of different 
computer systems. Apple's version of Smalltalk-80 is distributed under a license from 
Xerox Corporation. 


This release of Smalltalk-80 is intended to run on the Macintosh Plus with a hard disk. The 
Smailtalk-80 environment is very large, and is not feasible to run it on a smaller system. 
This becomes more understandable when you realize the entire source code to the 
Smalltalk-80 system is provided on-line. (The August 1985 release of Smalltalk from 
Apple also runs on smaller machines, such as.the 512K Macintosh without hard disk.) 


Smalltalk-80 consists of two separate logical parts, the user interface and programming 
environment, and the language itself. This is shown in the following diagram: 








The 
Smailtalk-80 
System 







User 
Interface 






"Smailtalk" is theTotality of the Environment (User Interface) plus the Language 
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The most basic characteristic of the Smalltalk language is that it is an object-oriented 
language. That is, it is based on the model of software objects that communicate with 
messages. This model is referred to as the Object/Message metaphor. Alan Kay, who 
originally conceived of Smalltalk, has said it was directly inspired by two other famous 
object-oriented languages, Lisp and Simula. 


The Smalltalk-80 environment and language is a very complex topic, and is further 
complicated because different kinds of users are interested in it. The book Smalltalk-80; 

ion, by Adele Goldberg and David Robson gives the 
most comprehensive description of Smalltalk in today's literature (see the Bibliography at 
the rear of this manual). 


Those writers summarized Smalltalk-80 by listing four basic attributes. They are: 


1- Smalltalk is based on a small number of concepts, but defined by unusual 
terminology. 

2- Smalltalk is a graphical, interactive programming environment 

3- Smalltalk is a big system. 

4- Smalltalk is a vision. 


To this list we might simply add: 


5- Smalltalk is an object-oriented language. 
6- Smalltalk is a very nice programming environment. 


Smalltalk the language is an object-oriented language. This might be an alien concept to 
those of you who have not been exposed to Lisp, Object Pascal or other object-oriented 
languges. However, the basic nature of Smalltalk can be explained with a small number of 
concepts and unusual Terminology. 


This unususal terminology will help you to re-think the most basic assumptions you have 
acquired using other programming languages. And your appreciation of algorithms-will 
increase after browsing the Smalltalk-80 system and viewing the source code of the 
"methods" (that is, the procedures and functions) that make up the Smalltalk-80 system. 


Portablility of the Smalltalk Virtual Machine 


Smalltalk-80 can and has been ported to a variety of machines. Although most of the 
system is implemented as Smalltalk System Classes (viewable in their entirety by you as 
Smalltalk source code), at the bottom of the implementation are Primitive Classes, written 
in the machine language of the host processor. Together, the System Classes and the 
Primitive Classes make up the Smalltalk-80 Virtual Machine, which provides: 


-object-oriented storage 


-message-oriented processing 
-graphically-oriented interaction 
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Why Smalltalk? 


The advantage of Smailtalk is a subtle, but powerful one. We have already explained how 
Smalltalk regards programming constructs in terms of Objects. What this means for a 
programmer is a different way of visualizing control flow. Rather than thinking as 
assembly language programmers (and programmers in traditional high-level languages with 
exactly the same segmentation and control flow philosophy), a Smalltalk programmer does 
not have to explicitly visualize the exact sequence and hierarchy of subprogram calls. 


With Smalltalk (or any object-oriented language), the large programming problem is solved 
not by decomposing the problem into a hierarchy of functional subprograms, to be 
orchestrated by the programmer, bringing them into play at a moment he is conscious of 
and selects. Rather it is solved by thinking of Objects (defined within Classes). Then, with 
a hierarchy of subclasses giving more detailed information about the classes that spawned 
them, the objects are defined in such a way that they decide when control will transfer to 
the subclass. In fact, conceptually it is no longer necessary for the programmer to think of 
control flow except within the local method being programmed. 


The History of Smalltalk 


Smalltalk was conceived by Alan Kay around 1973 when he worked in the Learning 
Research Group at the Palo Alto Research Center of Xerox Corporation. The lan guage 
was further developed in association with Dan Ingalls, who implemented most of the early 
Smalltalk interpreters. Another early contributor to Smalltalk was Larry Tesler. Since the 
early 1970's, Smalltalk has gone through at least five stages of evolution and revision, 
resulting in the current standard called Smalltalk-80, licensed from the Xerox Corporation. 


The focus of the Learning Research Group was the visionary mission to develop a non- 
traditional computer system which many different kinds of people could use pleasurably 
and effectively. It would take a different kind of programming language to more closely 
resemble the concepts in our minds and to avoid arcane mathematical constructs. Current 
languge theory suggests that such a language would be an object-oriented language, and 
that is what Smalltalk is. Smalltalk is probably not the last word in object-oriented 
languages, or in languages for ordinary people, but it is certainly among the most exciting 
and visionary languages and programming environments on the scene today. 


Object-Oriented Languages 


In attempting a general definition of object oriented languages, it becomes obvious that a 
few interrelated concepts must be defined simultaneously in term of each other. The 
‘problem is complicated by the fact that object-oriented languages are so different in their 
basic assumptions than the ordinary, procedural languages most of us were trained on. As 
an analogy, imagine that you are formulating a non-Euclidian Geometry. You would have 
to call into question and redefine one or more of the traditional common-sense axioms of 
that logical system. 


Similarly, to approach a definition of object-oriented language it is necessary cast away our 
previous ideas of a program "object," which we probably would think of as a "token", 
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"variable" or "data structure." But Smalltalk-80's definition goes beyond this, and 
associates "methods" (which are like procedures or functions) with the declaration of 
objects. The concept of "messages" between objects is also necessary to allow 
independent objects to interact. A complete definition of “object” also involves the 
interrelated concepts: class, superclass and subclass. 


Classes 


As the names suggest, classes are logical sets of objects (all defined the same generic way) 
that are defined in a hierarchy of other classes which are "above" ard "below" on a tree 
diagram of relationships. A class is said to inherit all characteristics of objects in the class 
"above", which is the superclass, and it adds further characteristics. Similarly, if a 
subclass is defined "below" the present class, it inherits all of the present class's 
characteristics and adds some others. This is suggested by the following diagram: 






Subclass 


Each step down this diagram shows "larger" classes because they inherit all the 
characteristics from the classes above and add others. 


Objects 


An object is a distinct entity that is an "instance" within a particular class. The object has all 
the characteristics the programmer defined for that class. The class, in turn, fits in the 
hierarchy, having a superclass (of which the class is a particular species) and possibly 
subclasses (which are differently defined subspecies of the class.) The advantage of this 
approach is that complex systems are built in a managable way from classes, subclasses 
and superclasses of objects. 
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The mechanisms of object-oriented languages allow objects to be defined in a manner that 
hides the true details of implementation. Often they are defined in terms of previously- 
defined objects, which allows an incremental building up of complexity. 


While Smalltalk was not the first object-oriented language (Lisp was a famous 
predecessor), it is unique as a language which uses objects (and messages) to implement 
the entire programming environment. Also, its application to a variety of programming 
problems is more general than a language like Lisp, which excels primarily in list- 
processing or artificial intelligence applications. 


The Interrelationship of 
the fundamental Smalltalk concepts 


The above discussion introduced the five interwoven concepts which allow us to define an 
object-oriented language like Smalltalk. The interrelationship of these concepts is also 
shown in this diagram: 





The Five Basic Concepts are Defined in Terms of One Another 


The complete interrelationship of the five definitions in this diagram helps explain why 
Smalltalk has such idiosyncratic terminology. A satisfactory definition of each of these 
terms depends on the others. The concept message is meaningful only when there are 
objects sending and receiving messages. Objects are only Instances of Classes. And 
Classes are defined in terms of the Messages they can send and receive, and in terms of the 
Methods which are the procedures that send and receive the messages. 
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Care and Feeding of your "Image" 


Smalltalk is somewhat unique as a programming environment in that there is no firm line 
between where the operating system leaves off and your own applications begin. You are 
free to modify the System Classes to suit you, and the methods you write will call system 
objects just as freely as the methods that make up the definition of System Classes. This 
gives you both power and responsibility. This section discusses some of the issues and 
mechanisms of backing up your Smalltalk-80. 


In Smalltalk-80, the .image file contains the executable image for the basic Smalltalk-80 
interpreter and environment. The .changes file must also be present. This includes all 
changes that have been made to your Smalltalk, either before it was shipped or by you, 
since the last image file was compiled. Both these files are necessary for the environment 
to run. As you interact with Smalltalk-80, both these files are constantly being rewritten. 
For example, when you Accept a new method into the system, it is compiled and written to 
the .image file. As explained below, on the Macintosh implementation the .image and 
changes files must be named with the same first part to their names. 


The following sections explain how to make a "snapshot" and otherwise back up the 
system. It is as important to back up critical code development that you may have 
undertaken. However, it is equally important not to permanently trash your Smalltalk by 
saving a system you have modified and might now be invalid. The only way around this is 
to keep plenty of copies around on external media of the image and .changes files through 
their various incarnations. Your skill with this will improve with experience, but if you 
make a mistake the worst that could happen is that you'd have to regenerate the original 
Smallitalk-80 as we released it. 


Save Frequently 


The Smalltalk-80 system is by nature a very malleable programming environment. Some 
of the changes you make may leave you with a dead system. A good rule is "Don't play 
for more than you would be happy to lose." Even if you never make a silly mistake, the 
power might go off, or you might find a bug that we don't know about. 


Making a Snapshot 


The snapshot mechanism allows you to save the exact state of your environment, down to 
which views were open and visible and what text was selected. You make a snapshot by 
first getting the Screen Menu by moving the cursor out of any active view and into the gray 
area of the screen. After a short time a tiny control panel will appear, and if you press the 
mouse button it will expand into the Screen Menu. Holding the mouse button down, move 
the mouse up and down until the snapshot option in the menu is blackened. Then release 
the mouse button to execute the command. You may then use the Screen Menu to get the 
quit option, or continue to work with the present Smalltalk state, knowing that you could 
load in the snapshot state if necessary. 
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The Maciutosh Implementation 


Here are some important items of information about how this version of Smalltalk-80 
resides on the Macintosh. Little things like what icon to double-click and how to maintain 
your desired changes. Also, the all-important backups, which in Smalltalk-80 you should 
make only if you are confident in your recent changes. 


Some of the terms used in the rest of Chapter 1 will be unfamiliar until you read Chapters 
3,4 and 5. But you can return later and use this part of Chapter 1 as a reference guide. 


System Workspace and ‘Hello’ File 


Many useful executable expressions have been collected in a window called the System 
Workspace in the Level 1 image. Because this text consumes valuable space, it has been 
omitted from the Level 0 image, but we have included an annotated copy as an appendix to 
this documentation. 


We have also included several interesting code fragments in a file named ‘Hello’. Here is 
what you need to do to open a window on that file. Once in Smalltalk, click the mouse in 
the window in the upper right corner of the screen. If it is not already selected, select the 
item (FileStream oldFileNamed: 'Heilo') edit. 


Selection is done just as in MacWrite. If there is no such text, you can type it, just as with 
MacWrite. When the text has been selected, slowly move the cursor into the white scroll 
bar at the left of the text area. In the rightmost edge of this area, the cursor should take on 
the shape of a little menu. When that happens, click the mouse button and hold it down. A 
menu will pop up on the screen, from which you should choose Dolt', and then release 
the mouse button. This causes Smalltalk to compile the selected expression and execute it, 
pora kas t.e effect of creating a new window viewing the contents of the file named 
Hello’. 


When the rile has been opened, Smalltalk needs you to specify a rectangular area for the 
window on the screen. The cursor should change to a bracket shape, prompting you to 
click where you want the upper left corner of the window, then it should change to another 
bracket prompting you to click where you want the lower right corner of the window. 
Once you have done this, the text in the file will appear, and it should tell you everything 
else you need to know. 


FileIn and FileOut 


You can save and load parts of your Smalltalk system -- individual methods, classes, 
groups of classes, and so on -- in a text file format called "fileOut format". The fileOut and 
fileIn operi.ions are available in browser menus and as messages of which there are 
examples in ihe System Workspace window. These files can be moved from one image to 
another, and can be read by MacWrite. You can even edit them in MacWrite if you are 
very careful not to disturb the file format conventions, and save as text-only. 


Note that browsers do not properly reflect changes made in other browsers or in fileIns. It 
may be necessary to reselect an item or, in some cases, even to close and reopen the 
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browser. The update option in the leftmost panel causes a browser to show new system 
categories which have been created by another browser or by a fileIn. 


Smalltalk State 


Two files, an image and a changes file (by convention named xxx.image and 
xxx.changes), together, constitute the full state of a given Smalltalk system. Therefore, 
to completely back up the state of your work in Smalitalk, you must save copies of both of 
these files. You may rename the copies at will, but you must abide by the convention that 
the two names begin the same, and end with .image and .changes. 


The Image and the Changes File 


If you become a serious user of Smalltalk, you will find it useful to understand how the 
changes file (Smalltalk-80.changes) is used. Each tinie you accept a method, or execute 
an expression (do it) in Smalltalk, a copy of the source code in question is appended to the 
changes file. This file provides the necessary data to later browse the source code for the 
changes you have made. 


Since the changes file constitutes a log of changes you have made, it can be very valuable 
in case of disasters. In the System Workspace yo. will find the executable statement, 
Smalltalk recover: 5000. This will copy the last 5000 characters of the changes file to 
a temporary file and prompt you to open a window on that text. In that window, you can 
select important lost information, and re-execute it tc recreate the changes you lost. The 
changes file is in fileOut format. The file window includes a menu command fileItIn, 
which will cause a fileln of the currently selected portion of the file. In the case of method 
definitions, the methodsFor: line which precedes the definition must be included, as well - 
as the exclamation points that delimit the end of the method definition item. The longest 
recovery that can be effected in this way is current]: the practical file size limit of 16000 
characters imposed by the file edit window. 


The changes file grows every time you run Smalltalk. If you redefine a method twenty 
times, there will be twenty copies of it in the changes file. Also, even when you quit 
Smailtalk without saving changes, the changes file will have grown as a result. Eventually, 
it will be necessary to condense the changes file - that is, to write a new copy which 
contains only the code currently accessible from the image. This can be accomplished by 
executing the statement Smalltalk condenseChanges. It is advisable to make a backup 
copy of your state (.image and .changes) before condensing the changes file. The 
process can take a long time (10 minutes or more), depending on how many changes you 
have made in your image. 


*** [ Probably Omit the Following: ] ** 


Users without hard disks will have to pay particular attention to the amount of space 
remaining on the disk used for changes. The condensing process itself requires additional 
space for the condensed copy, so one should ideally condense the changes file whenever it 
becomes as large as the free space remaining on the disk. If one is attempting serious work 
without a hard disk, this restriction may become a problem. In such cases, you may fileIn 
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the goodie named dropChanges.st, and then execute Smalltalk dropChanges. The 
result will be to reclaim all space in the changes file, but future browsing of the changes 
made up to that time will only present a decompiled version of the code - in other words 
temporary names and comments will be lost. If you must resort to this solution, you 
should probably save fileOuts of the code you care about, so as to retain a copy of the code 
with commments. 


The Change Set 


Besides the changes file itself, the Smalltalk-80 system provides another completely 
independent mechanism for recording what changes have been made. While the changes 
file is a linear log which records all the text involved, the changes set holds references to 
changes made to the classes and methods within the system. It is used in conjunction with 
the fileOutChanges method. For example, executing 

(FileStream newFileNamed: 'Jan26/Changes.st') fileOutChanges 
will cause every change recorded in the change set to be written out to the named file. Such 
"fileOut" files are a much more compact way of saving a Smalltalk project than saving the 
whole image. If you use project windows, a separate change set is maintained for each 
project window in your Smalltalk. Note that the statement 

Smalltalk noChanges 
can be used to reset the current change set. If three more changes are made thereafter, only 
those three changes, and no previous changes, will be recorded. 


Whenever a fileout includes a class initialize message, it will also automatically generate a 
statement to invoke this method at the end of the file. 


Summary 


We have given an overview of the most basic concepts and terminology of Smalltalk. 
Later, especially in Chapter 4, much more detail about the Smalltalk-80 environment and 
language will be given, hopefully enough to make real work with the system possible. It 
will be very rewarding to master a language like this if you invest the effort. As 
motivation, consider the ease of writing programs in a language like Smalltalk that takes 
advantage of the object-oriented philosophy and incrementally adds levels of complexity. 


And above all, remember: "Smalltalk is a Vision!" 
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Chapter 2 


Installation 


Installing Smalltalk-80 with a Hard Disk 


To run Smalltalk-80 on a Macintosh Plus with a hard disk, your hard disk must be 
capable of holding the following files plus some 1300K of working space (roughly 


3500K total): 
1300K  Smailtalk-80.sources 
STTK image 
24K „changes 


56K Smalltalk (interpreter) 
67K 12 examples (.st) 
36K DivJoin. 


This release is shipped on three Macintosh diskettes. All files needed to run are on the 
first diskette. Because of the size of the sources file, it has been split up into two files 
named 


1.Smalitalk-80.Sources and 2.Smalltaik-80.Sources. 


First copy all the above files to your hard disk, and then use the DivJoin program to 
reconstitute the two large files from their constituents. DivJoin is a program that allows 
very large files to be stored on diskettes by breaking them into pieces (each of which fits 
on a diskette) and reassembling them again on a hard disk. 


To reconstitute the sources file, first double click on DivJoin. Once inside DivJoin, select 
Open from the File menu and choose 1.Smalltalk-80.sources. Now select Join 
this File from the Div/Join menu to join the other part of the source file together. If you 
need more space at this point on your hard disk, you can leave the DivJoin program and 
delete 1.Smalltalk-80.Sources and 2.Smalltalk-80.Sources. 


You can minimize the amount of space needed during installation by moving and 
reconstituting Smalltalk-80.sources before moving any of the other files to your 
MacWorks volume. In this way you could get by with around 2500K of disk space. 
However, you will probably want more space for the convenience of keeping a backup 
copy of the image and changes, so as to avoid the full installation procedure the next time 
you want to start from a clean copy of Smalltalk. 
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Starting Smalltalk 


To start Smalltalk after it has been installed on your hard disk, double-click or open the 
.image icon. It takes about half a minute to load the image into memory, after which the 
malltalk screen is displayed. 


Alpha Draft 24 5/30/86 


Chapter 3 


Introduction to the 
Smalltalk User Interface 


Start up Smalltalk and Browse Around 


Assuming you have installed Smalltalk-80 on your Macintosh Plus, you can activate the 
system simply by double-clicking on the .image icon (pot the icon called "Smalltalk"). 
There will be a delay of a minute or two while the system initializes. It is recommended 
you start Smalltalk now if you haven't already, because it is a system which is best leamed 
by exploration. In fact, the designers of Smalltalk intended "browsing" to be the basic way 
to interact with the system. 


Each time you start up Smalltalk-80, you will see a set of views (windows) across the 
screen. Exactly what views you will see depends on what changes you have loaded and 
accepted as your permanent system, or what state things where in at your last snapshot. 
However, in the original default screen, used the first time you start up this release of 
Smalltalk-80, you see the five views shown in the figure below. In this figure, the default 
active view is the System Browser. Because the Macintosh has made the graphic-based 
windowed environment quite familiar to us, we instinctively realize that to explore such a 
system is simply a matter of clicking on windows, "growing" them, and scrolling in them. 
However, the windows in Smalltalk are called views (sometimes called "panes"), 


Class Message Message 
i Categories Categories | Selectors 


Text of 
Smalltalk Code 





Smalltalk-80 Startup Screen 


The first time you start up this Smalltalk-80, it starts up in "The System Browser." From 
left to right the views at the top of this startup screen are: 
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- Class Categories 

- Class Names 

- Message Categories 
- Message Selectors 


The larger full-width area at the bottom of the screen is the Text Area for actual Smalltalk 
code. 


The contents of the Class Name view will change depending on what item you select (that 
is, darken by pointing and dragging) in the Class Categories view. Similarly, if you select 
a different item in the Class Name view, different items will appear in the Message 
Categories view. Finally, your selection in the Message Selectors view will determine 
what Smalltalk code you will see in the large Text Area at the bottom of the screen. 


The meaning of the terms Class, Message, and so forth will be more familiar to you after 
reading Chapter 4 of this book, "A Short Course in the Smalltalk-80 Language." 


How to Interact with the Views 


Despite the similarities, the Smalltalk-80 user interface varies somewhat from the 
Macintosh standard interface. For example, to make a view "active" you need only move 
the cursor into its area, rather than clicking on it. You can select text, either to edit it or 
execute a command, just like in MacWrite. That is, you point to it with the mouse, click 
and drag across the selection, which will turn dark. Editing text is described below, as is 
activating commands through menus. 


Scroll Bars 


Just like in Macintosh, the full contents of a view are usually not visible at any given time. 
Scroll bars are provided (similar to Macintosh "elevators") to select what portion will be in 
sight. Try this out by moving your cursor into the "Class Categories” view of the 
Smailtalk-80 startup screen. After a short pause, the scroll bar will appear in a narrow 
rectangular window at the left side of the active view. Inside the narrow window is a gray 
bar which is the scroll bar itself. The height of this bar is equivalent to the proportion of 
the whole contents that are currently visible. To scroll, move the cursor above or below the 
gray bar and click the mouse button. The bar will jump up or down, and the view will be 
repainted with different information. 


Pop-up Menus 
Users of Macintosh are familiar with pull-down menus that run across the menu bar at the 
top of the screen and provide access to commands and functions. Smalltalk-80 also 


provides command menus, but they are of the pop-up variety, and appear all over the 
screen depending on which view is active and which type of button you press. 


Use of Smalltalk Buttons 
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There were three different mouse buttons on the original Xerox Smalltalk systems (called 
Yellow, Blue and Red buttons), and using each caused a different kind of menu to 
appear. On the Macintosh, there is a specific way to use the single mouse button to get 
each type of menu. The above example for the Screen Menu employs the "Yellow Button." 
When you move the cursor into a gray area on the screen and press the Macintosh button, 
you always get the Screen Menu, or global command function menu. Clicking the mouse 
button in the gray area corresponds to the old "Yellow Button". (See the subsection below: 
"Commands to Smalltalk80: the Screen Menu.") 


Example: One of the options in the Screen Menu is "open workspace." Try this option 
by clicking on the gray area to get the Screen Menu. Still holding the mouse button down, 
move the mouse until the "open workspace" option is darkened. Then release the button 
and you will see the cursor change shape, forming the upper left corner of a rectangle. 
Move the cursor somewhere towards the center of the screen and press the mouse button 
again. (The mouse button is now serving as Red Button — see below.) Drag towards the 
lower right and a rectangular window will be opened. When it is large enough, release the 
button, and your new workspace will ready for editing. (Refer to the section below, "The 
Editor.") 


More Yellow Button: The Yellow Button is also used to get a menu for editing the 

contents of a view. Rather than clicking on the gray area outside the windows, you can 

click on the right edge of a scroll bar, or use the Option key as a shift to make an ordinary 
- mouse click a Yellow Button regardless of where the mouse is. 


Red Button: Besides helping shape a new workspace, the Red Button also functions to 
select text within any view, such as a workspace or a system view. Moving the cursor into 
the view with the text to be selected and to the start of the selection, the red button is 
pressed once. A small carat appears indicating the start of the selection. Then the cursor is 
moved to the end of the selection and the red button is pressed again. The entire selection 
is displayed in reverse video and appears dark. Or, the red button is clicked only once to 
mark the insertion point for text. 


Blue Button: The Blue Button menu is obtained with the Macintosh by clicking in the 
window title tabs. Alternatively, you can use the Enter key as a shift, which turns the 
mouse button into Blue Button regardless of where the cursor is. The Blue Button can be 
used to get options within a workspace or other view such as "collapse" or "close." 


LE E E 


Old explanation of mouse buttons: 
Ad 


Mouse Buttons 

You can click in right edge of a scroll bar for the yellowButton menu. 

The Option key works as a shift to give "yellow" button when otherwise needed. 
You can click window title tabs for the blueButton menu. 

The Enter key works as a shift to give "blue" button when otherwise needed. 
Click in the gray area outside all windows for the screen menu 


Lai.) 
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Commands to Smalltalk-80: the "Screen" Menu 


All commands you give to the Smalltalk-80 system are given via menus which are activated 
by pointing the mouse to the appropriate region of the screen and using the mouse button. 
Which region of the screen depends on whether the command applies to the contents of a 
particular window or view, or whether it is "global" or high-level. 


High-level Smalitalk-80 commands, such as saving your state and quitting, are done by 
selecting options from the Screen Menu. Point in a gray area where there is no window 
and hold the mouse button down (don't let go!). The screen menu will appear, presenting 
a choice of several global operations, such as restoring the display, opening new windows, 
making a snapshot, and quitting. Move the cursor to the command you want -- or outside 
the menu if you don't want any of them — and then release the button. 


Screen Menu Options: Save and Quit 


Making a snapshot is like the save operation in most Mac software, but it causes the 
entire state of your Smalltalk ~ not just the active window — to be written back onto the 
image file, after which you may continue working in Smalltalk. If you make an 
unrecoverable error, or if Smalltalk should crash, restarting Smalltalk will return you to the 
state at your last snapshot or quit-with-save. 


The quit option is like the quit operation in most Mac software. It first prompts you to 
choose whether to save the changes you have made. If you choose no, then the next time 
you run Smalltalk, none of the changes since you started (or since your most recent 
snapshot) will remain. If you choose yes, then the next time you run Smalltalk everything 
will be just as you left it - all the windows will be where they were, even interrupted 
processes will remain in a state of suspended animation. (Note, therefore, that if you 
suspect your Smalltalk to be flawed, you should not snapshot or save changes at quit.) 
Open files will be closed by the Snapshot and Quit operations, and they will be re-opened 
automatically upon restarting Smalltalk. 


The Text Editor 


The Smalltalk-80 text editor allows text to be modified in any view where it is found, or in 
a new workspace that you create. This text editor is similar to MacWrite in that you point 
to areas where text is to be inserted and you use the mouse to select text to be deleted or 
copied. The following “control character" sequences are recognized: 


The Smalltaik-80 goes beyond MacWrite in such areas as Automatic Spelling Correction. 


[ ** More information will be drafted. * ] 


Keyboard and Editing Operations 
Apple-X, C, V are keyboard synonyms for cut, copy, paste. 


= 
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Use shift-6 to get up-arrow, shift-minus to get left-arrow. 

Use Apple-period for keyboard interrrupt (used to be control-C). 
Text selection can be extended by shift-clicking. 

Typing does not interfere with the paste buffer. 

Paste does not leave an extended selection. 


Spelling Correction: Spelling correction in this Smalltalk is automatic, rather than 
voluntary, and you have the opportunity of choosing among the closest matches. The 
correction algorithm favors messages that begin the same, but you can choose try harder 
to include a wider variety of messages in the search. 
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Making Pictures in Smalltalk 


Smalltalk-80 offers three ways to make pictures. The first two ways involve interactive 
editors known as the Form Editor and the Bit Editor. The third way involves using 
software to send messages to instances of Pen to create images on the screen. 


This manual will introduce the first two ways. The Form Editor involves "painting" with a 
"brush", similar to MacPaint, and the Bit Editor manipulates individual pixels on the screen 
much like Fat Bits within MacPaint. 


Using the Form Editor | 


The Smailtalk-80 Form Editor allows the "painting" of bit-mapped images. The Form 
Editor uses the metaphors of canvas and a brush that is controlled by the mouse. When the 
Form Editor is activated, a large window called the canvas is opened, and along the bottom 
of the screen is a "pallette" of iconic tools which certainly is reminiscent of MacPaint. This 
is called the Iconic Menu. It is visible only when the view for the Form Editor is 
selected. To choose any tool in this menu, move the cursor over the desired icon and click 
the mouse button. Then try painting with the mouse and see what happens. But first, you 
must activate the Form Editor. 


One way to activate the Form Editor is to create a workspace and type in the following 
expression: 


FormEditor openFullScreenForm 
Then Evaluate this expression by selecting it by clicking and dragging and using the Blue 
Button to obtain a menu. Select Dolt from this menu and the expression is evaluated. 
This will create an editor for a Form that fills nearly the entire screen space. 


A complete guide to using the Form Editor is beyond the scope of this manual. We 
recommend pure exploration! 


Using the Bit Editor 
The Bit Editor is invoked from the Form Editor, or by evaluating an expression like: 

Form fromUser bitEdit 
Either way, you first designate the rectangular area on the screen fiom which the Form is 
defined. Then you designate the top left corner of the area of the magnified view. This 
area contains both the magnified and unmagnified views. Editing takes place in the 


magnified view. The mouse button is then used to set dots either to black or white, using 
selections from the icon menu that appear below the view. 
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Finding Information in the Smalltalk-80 System 
Finding out information in the Smalltalk-80 system. means finding out information about 
Objects. The internal state of an object is examined using a system view called an 


Inspector. The message interface to an object is examined using a system view called an 
Browser. 


Inspectors 


The inspectors in this Smalltalk have an extra panel at the bottom. Here you can type and 
evaluate expressions in the context of the inspected object, without their being overwritten 
by the display of field values. 


Browsers 


Using a Browser to View an Instance 
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What's Important "Inside" Smalltalk ? 


The following section tells how to use the System Browser to view important System 
Classes. To know what are the more important Objects, Classes, and Methods in the 
Smalltalk-80 system, refer to the detailed treatment of these topics in Chapter 4 (the major 
section titled The System Classes), and in Chapter 5. 


Viewing Class Definitions with the System Browser 


From the discussion in Chapter 1, you will be aware of Classes. In the Smalltalk-80 
programming language, each new class must be defined in a Class Definition, which is a 
textual description of the class. As implied there, the whole Smalltalk-80 system is itself 
constructed from System Classes. The entire source text for the system is available on-line 
(a large amount of code). So the question becomes, how to conveniently view the 
Smalltalk-80 source. The answer is, with the System Browser, an interactive, 
structured editor that opens in a view. (The first time you start up this release of Smalltalk- 
80, the default active view is the System Browser.) A browser is part of the programming 
interface. It is used in a running Smalltalk-80 system. 


(There are other ways in Smalltalk-80 to present classes, such as a Protocol Description or 
an Implementation Description. These topics are are discussed in Chapter 4 under the 
heading Presenting (Viewing) Classes. 


To use the System Browser, 


Using Projects 


File System 
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A Short Course in the 
Smalltalk-80 E 
Language and Environment 


Overview 


In Chapter One the five most basic concepts of the Smalltalk language were introduced: 


Object 
Class 
Instance 
Method 
Message 


Now we will build on these basic concepts, and attempt to give an overview of the rich and 
elaborate system that is the Smalltalk-80 language and environment. 


This chapter is a "Short Course" covering not only the syntax and usage of the Smalltalk- 
80 language itself, but also the environment of Smalltalk-80, which is implemented from 
System Classes, collections of classes, and primitives, all of which you can view. And it 
is probable that your programs written in the Smalltalk-80 environment will send messages 
and interact with the objects making up that environment. (By "environment" is not meant 
"user interface,” which is covered in Chapters 3 and 5). 


Roadmap to this Chapter 


This chapter is divided into four main sections: 


1- The Basic Five Concepts of Smalltalk 

2- Language Syntax and Control Structures 
3- The System Classes 

4- The Collection Classes 


This chapter is sufficiently long that you may not realize where the part you are reading fits 
in the whole subject. To help locate each section and subsection, a roadmap to the Chapter 
is shown in the following diagram: 
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7 Five R 
Concepts Collection 
Classes | 





Roadmap to Chapter 4 


Outline of this Chapter 


In addition to the diagram on the previous page, we are providing the following outline of 
subsections for this chapter: 


The Five Basic Concepts of Smalltalk 
Object, Class, Instance, Method and Message 
Presenting (Viewing) Classes 
Classes and Subclasses 
Messages 
Methods 


Language Syntax and Control Structures 
Language Syntax 
Control Structures in Smalltalk-80: Blocks 


System Classes 
System Classes: “Linear measures:" Class Magnitude 
System Classes: “Linear measures:" (Others) 
System Classes: "Linear measures": Numerical Classes 


Collection Classes 
Class Bag 
Class Set 
Class Dictionary 
Class Sequencable Collection 
Hierarchy of the Collection Classes 
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The Basic Five Concepts of Smalltalk 


Object, Class, Instance, Method and Message ° 


It is important to fully understand the exact meanings of the interrelated terms Object, 
Class, Instance, Method and Message. A Class is the description of the implementation of 
a set of Objects that all represent the same kind of system component. Each distinct 
object within a class is called an instance. (Indeed, every Smalltalk-80 object is an instance 
of some class.) The name given to a class is somewhat descriptive of the type of 
component its instances represent. (Class names appear in a special font so that they can be 
picked out of a complex program listing.) 


A class describes the form of the private memory, which is the same for each instance of 
that class. A class also describes how the instances will carry out their operations. The 
mechanism that triggers all activity is the Message, from one instance of one class to 
another instance of another class. 


The instances of a class all respond to the same messages. (The set of all messages 
responded to by the instance is called its interface.) Each message responded to by a class 
Tequires an operation to be performed by its instances. Each operation is described by a 
Method. 


A Method in Smalltalk-80 is analogous to a procedure or function in languages like 
Pascal. A class contains a method corresponding to each type of message the instances of 
the class responds to. In other words, a method for each type of operation the instances of 
a class might perform. A method might specify some change to the variables in the private 
memory of the instance, or specify a message to send to another object. 


Note that a method is only executed in response to a message. 


Presenting (Viewing) Classes 


The two basic ways to present or view a Class are: 


1 - Protocol description, a list of the messages understood by instances of the 
Class. 


2 - Implementation description, giving the form of the instances’ private 
memory and 
the code for each method showing how the instances’ operations are carried out. 


(There is also a third way to present a class: an interactive view with a system browser. 
This topic is covered in Chapter 3.) 


Protocol description of a Class 


A Protocol Description of a class lists the messages understood by instances of that class. 
Each message is described as message patterns, consisting of a message selector and one or 
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a few argument names. . (So-called unary messages don't have any arguments.) The form 
of actual messages will be based on the message selector listed in the protocol description, 
but each actual message will consist of different symbols or names in each position of the 
pattern. id 


Message Categories 


Within a class definition, messages that invoke similar operations are grouped together in 
Categories. 


Implementation description of a Class 

Another way to view a class is its Implementation Description, consisting of three parts: 
1- a Class name 
2- a declaration of the variables available to the instances 
3- the methods that respond to messages to the instances 


A discussion of Methods is later in this Chapter. Variables of five different kinds can be 
declared, as discussed in the following section. l 


Variable Declarations 

The scope of variables, and whether a variable will be accessible to a particular method in a 
particular class, depends on which kind of variable was originally declared. There are five 
kinds of variable Available only to a single object: 


1- Instance variables - lifetime of object. 
2- Temporary variables - only for duration of activity. 


Available to more than one object: 

3- class variables - (shared by) all instances of single class. 
4- global variables - (shared by) all objects. 

5- Pool variables - (shared by) a subset of classes. 


The kinds of variables that can be declared are also summarized in the following diagram: 
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An Implementation Description of a class includes a set of names for the named instance 
variables that are used by the particular incarnation of the class, that is, by the instance. 
Another kind of instance variable is the indexed instance variable, which is not 
accessed by name. Any message involving an indexed integer uses a small integer as an 
argument. This integer is an index to the particular variable, which needs no other name. 


Classes and Subclasses 


Subclassing is strictly hierarchial. It doesn't allow more arbitrary intersection of class 
boundaries, 


In this context, hierarchial means: "If any instances of a class are also instances of another 
Class, then all instances of that class must also be instances of the other class." 


Subclass Defined 


A subclass is in all respects a class. It specifies that its instances will be the same as 
instances of another class, called its superclass, except for the differences that are explicitly 
stated. A subclass can have subclasses itself. 


When programming in Smalltalk, one must always be conscious of where one is on the 
hierarchial tree of classes, superclasses and subclasses. 


Metaclasses A-W blue p. 76 


A metaclass is a class whose instances are themselves classes. Each class is an instance of 
its metaclass (created automatically). 


* RK KK 


A-W blue p. 107 
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"Smalltalk provides several classes representing objects that measure something with linear 
ordering, such as temporal quantities such as date and time, spacial quantities such as 
distance, and numerical quantities such as reals and rationals. " 


eee 


Messages 

Messages cause the interactions between the objects in the Smalltalk-80 system. A 
message requests an operation from the receiver. The Message is the only activator of 
methods within instances of classes. 

Exampes of messages: 

- Messages to numbers representing arithmetic operations. 


- Messages to linear data structures representing the addition or removal of information. 


- Messages to associative data structures (such as dictionaries) representing the addition or 
removal of information. 


- Messages to rectangles representing graphical inquiries and calculations. 


- Messages to financial history records representing transactions and inquiries. 


Form of messages 


"A message expression describes a receiver, selector and possibly some arguments. 
The receiver and arguments are described by other expressions. The selector is specified 
literally. 


"A messages selector is a name for the type of interaction the sender desires with the 
receiver.” 


The form of a message is: 


< receiver > < selector > { arguments } 


Messages can return values. A-W blue p. 27: 


"Smalltalk-80 messages provide two-way communication. The selector and arguments 
transmit information to the receiver about what type of response to make. The receiver 
transmits information back by returning an object that becomes the value of the message 
expression." 
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Note: "If the message expression includes an assignment prefix, the object returned by the 
receiver will become the new object referred to by the variable.” 
Example: sum<-3+4 


On the surface, this example resembies the assignment statements from ordinary languages. 
But in Smalltalk, the string "3 + 4" is not a simple sum from arithmetic but rather is a 
message! (Binary message.) "3" is the Receiver, "+" is the Selector, and "4" is the 


Argument. 


"3 + 4" returns an object (i.e. "7") as the value of the message. Since the message 
expression contains the assignment prefix "<-", the variable "sum" is assigned the value of 
the message, and now refers to the object returned by the message as its value. 


Transmitter Class ... Receiver Class 


When a message is sent to an object in a class, its methods are searched for one with a 
matching selector. If none is found, the methods of the superclass are searched next. 


"Transmitter" "Receiver" 
CLASS y _ CLASS 






“Message “> 






Methods are contained “in” the Class that receives a Message 


The position in the hierarchy of classes and subclasses of the Transmitter Class and the 
Receiver Class must be understood. A method might contain a message whose receiver is 
self. (There also might be a message to super. This topic is beyond the scope of this 
manual.) ; 
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Methods 


The other part of an implementation description of a class is the code for all the methods 
needed by that class. To implement a class, a programmer must plan all the types of 
messages that will be received by instances of that class. Then, the writing of methods is 
essentially implementing the actions needed to provide the processing or data that is 
requested by the messages. 


A method has the form: 
method : message pattern + (list of) expressions separated by periods 
where message pattern is: 
message pattern : message selector + (list of) argument names 
Only one pattern in a class may have a given selector in its message pattern. 
The Return Operator (up arrow) preceeds any expression in a method that returns a 


value. 


**Other Topics on methods to be written include: 
Argument Names 
Returning Values 
The pseudo-variable self 
Temporary Variables 


Primitive Methods 


Accepting a Method 


When you write a Method (an application or "system" method) after you are sure it is right 
you can use the Accept command to integrate the selected new method into the Smalltalk 
system. 


$ 


The original Image, plus the Changes file, makes up the current state of the ST system. 
(This is different from most programming languages and environments, where the user 
program is regarded as separate from the "system." 
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Language Syntax and Control Structures 


Language Syntax 


Variable declarations have been discussed already under "Implementation Description of a 
Class." Now further aspects of the Smalltalk-80 language syntax are covered. 


Expression Syntax 


What is an expression? Much the same as in ordinary languages, they are combinations of 
symbols (literals or variables) and operators. They (often) require evaluation before 


further action can be taken. 
Types of 
Expression 






deferred actions 






Further breakdown: 
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See the discussion on Class Number for still further breakdown. 


Assignment Statements 
The assignment statement in Smailtalk-80 is very simple. Here is an example: 


quantity <- 19 


Control Structures in Smalltalk-80 


The traditional algorithmic control structures (as pioneered in Algol and seen today in 
Pascal, "C" and the like) also present difficulties when implemented with a strict 
object/message philosophy. Smalltalk-80 deals with this successfully, but its approach 
seems mysterious at first if you are used to more ordinary, non-object oriented languages. 


The fundamental control structure used in Smalltalk-80 methods is the sequential evaluation 
of expressions. Non-sequential control structures can be implemented with Blocks, 
which allow conditional selection and conditional repetition. 


Blocks 


A block expression (a sequence of expressions enclosed in brackets and separated by 
commas) represents a deferred sequence of actions. Blocks are used in many of the 
control structures in the Smalltalk-80 system. 


Example: 
[index <- index + 1] 


The statements enclosed in the brackets are not executed immediately when a block 
expression is encountered. An object takes on the value of a block expression, and it can 
execute these enclosed expressions at a later time, when requested to do so, by the unary 
message value. 


Blocks: Control Structures 


The usual control structure in Smalltalk-80 methods provides that a sequence of 
expressions will be evaluated sequentially. However, non-sequential control structures can 
be implemented with Blocks. These control structures are invoked either by sending a 
message to a block or by sending a message with one or more blocks as arguments. The 
order of activities is determined by the pattern of value messages one of these control 
structure messages sends to the block(s) the response to the message. 


Blocks: Conditionals 
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Conditional selection and conditional repetition are two common control structures 
implemented with blocks. 


Blocks: Arguments 
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System Classes 


System Classes: "Linear measures:" Class Magnitude 


The common protocol for answering all decisions as to whether one object is “more” than 
another (objects such as numbers, dates, characters in ordered sets) is provided by Class 
Magnitude. 


System Classes: "Linear measures:" (Others) 


Class Date 
Class Time 
Class Character 


System Classes: "Linear measures": Numerical Classes 


One of the more remarkable aspects of the Smalltalk system is its treatment of numbers. 
Earlier object-oriented languages embedded ordinary number representations and 
operations rather than coping with the problems of expressing them purely as objects. In 
Smalltalk, the object/message metaphor is consistently applied even to numbers. All kinds 
of numbers are painstakingly defined in their own classes, and the ordinary operations 
between numbers are defined as message transactions between objects. 


In the Smalltalk system, numbers are "used to perform mathematical computations; they are 
also used in algorithms as indices, counters, and encodings of states or conditions." 
Integer numbers (viewed as bits) are also used for boolean masking operations. 


The number classes collectively share a common protocol, under Class Number. There are 
subclasses for each different kind of numerical value. 


There are classes for Floats and Fractions, three kinds of Integers and even a class for 
random number generation. 


As shown in the folowing diagram, the numbers in Smalltalk are implemented either as a 
literal, or with a non-decimal radix, or with scientific notation. 
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cientifi 
not. 


Another way of breaking down Class Number is: 
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Collection Classes 


Sometimes it is convenient to group similar Smalltalk-80 objects. Such a grouping is called 
a Collection. 


In particular the Smalltalk-80 programming environment is implemented with Collections 
that provide basic data structures for programming in the Smalltalk-80 system. 


Some collections are ordered, some unordered: 


Ordered 
Collections 


Ordered collections: 








Sorted 
Collections 





*** Other Topics: 


Class Bag 

Class Set 

Class Dictionary 

Class Sequenceable Collection 
Class Ordered Collection 
Class Sorted Collection 
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Class Linked List 
Class Internal 
Class Arrayed Collection (string ... symbol) 
Class Mapped Collection 
Conversions among collections 


Hierarchy of the Collection Classes 
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Chapter 5 


Smalltalk-80 
Advanced User Interface 


#* The goal for the second half is to cover important User Interface and Programming 
Environment topics that couldn't be handled in Chapter 3 without the Language Concepts 
presented in Chapter 4. Such as how to browse and modify Classes. How to send a 


Message to an object, etc. ** 


[** Note to Reviewers: This Chapter is Not Yet Available **] 
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Chapter 6 


Implementation Details 
on the Macintosh 


Differences from Other Smalltalk-80s 


We have found it necessary or convenient to depart from the specification of Smalltalk-80 
which is documented in the Smalltalk-80 literature. We list on this page the chief 
differences that will be noticed by users with experience on other systems. 


Bw E. 
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Memory Space 


You may be interested in the question of how to make more free space available. We offer 
a few tools and a few suggestions, and we request that, if you have good success, you let 
us know what you did, so that we can pass it on to other users. 


For measurement, you will find Smalltalk printSpaceAnalysis (only in level 1 - use 
fileOut to move it, or write your own) useful. It lists on a file roughly how much space 
(objects and words) is consumed by each class and by instances of that class. 


Here are some suggestions about how to reclaim significant amounts of space: 
Remove FileLists (simply execute FileList remove). 


Remove the debugger step and send commands, and any other code which uses the simulation in class 
ContextPart. If you can't live without step and send, then implement breakpoints (a useful thing to do 
anyway), and then use these to restore the operation of step and send. 


Make MessageSet, and maybe even the Debugger, be a subclass of Browser so that they can share code for 
printing, fileOut, senders and messages. 


If you have a hard disk, remove the decompiler (simply execute Decompiler remove). One minor problem 
is that the decompiler is currently used for viewing the code of do-it methods from the debugger. If you 
can't live without this, then figure out how to log the text of do-it methods in the changes file and give 
them a proper source code pointer. 


After removing significant parts of the system in this way, you can use Smalltalk 
removeUnSentMessages. This method locates any messages which are implemented, 
but nowhere sent in the system, and then removes then. It is useful to run this method 
several times in a row (like 5), because each method removed may render other methods 
inaccessible. This method takes a long time (from 5 to 25 minutes) to run. 


Finally, you should run Symbol rehash, which will reclaim all the Symbols which are 
no longer in use as a result of the removal of methods. 


Memory Management 


The interpreter furnished with this release uses garbage collection rather than reference 
counts to reclaim unused storage. For this reason, it is not necessary to break circular 
structures in this implementation, though you will find many places where such "release" 
code still exists in this image. You will notice occasional pauses in the operation of the 
system when garbage collection takes place. Some of these take longer than others, and we 
are working hard to make them all shorter. 


A side-effect of the incremental garbage collection scheme used in this implementation is 
that Behavior allInstances and related enumeration messages will sometimes enumerate 
objects that are no longer truly accessible. If you want to be sure of the results, execute 
Smalltalk garbageCollect immediately prior to such enumeration. 


Even with garbage collection, it is still possible to run out of memory. If there is enough 


space in your system, a NotifyWindow will appear telling you that space is low. The stack 
of senders will allow you to check if the cause was endless recursion. It is generally 
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advisable to close the NotifyWindow, rather than proceeding, since there will be no soft 
error recovery possible after proceeding. If the problem was not an endless recursion, you 
should consider how you might have unintentionally consumed a lot of storage. In some 
cases you may have to jettison some other competing objects in the system. Level 1, 
contains a method SystemDictionary deleteClasses which performs such a jettison 
operation. 


You can find out how much memory is available in your system by printing 

Smalltalk spaceLeft 
which retums the number of free objects and number of free words of data. The minimum 
safe operating margin is around 1000 objects and 4000 words of data. 


System Sources and File Servers 


Smalltalk always expects the system sources to be named Smalltalk-80.sources. If 
there is no file by that name, Smalltalk will use decompilation to show source code for 
system methods. Each time Smalltalk starts up, it checks every mounted volume for the 
files it needs. Consequently, if your Macintosh is on a network, and if there is a disk 
server on that network, and if that disk server is "mounted" as a volume on your 
Macintosh, and if there is a copy of Smalltalk-80.sources on the disk server. . . guess 
what. ..Smalltalk will open the file over the network for its access to sources. In this way 
it is possible for many Macintoshes without hard disks to browse full source code if they 
are connected to a network with a disk server. 
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The Macintosh File System 


This implementation of Smalltalk-80 includes an interface to the Macintosh file system. 
Instances of MacVolume refer to the various disk directories. Files can be opened by 
sending messages to FileStream, such as FileStream fileNamed: 'Hello'. Several 
examples appear in the System Workspace. There is a default volume on which a file name 
will be sought, but you can override this by including a prefix (with colon) in the file name, 
as in "Internai:fileName'. If you don't know what volumes are available, you can use ? 
in place of the volume name, as in '?:Hello', and Smalltalk will present you with a menu 
of the currently mounted volumes and their aliases. You can eject a volume by sending it 
the message eject, or by choosing eject disk from the screen menu. If there are files 
open on this volume, you will be prompted to close them before ejection. 


Files in the Macintosh file system are modelled by instances of MacFileStream. These 
respond to normal stream protocol, a well as to several other messages which can be found 
by browsing through the implementation. If you overwrite an existing file, it is necessary 
to send the message shorten to the fileStream prior to closing, lest part of the old data 
remain after the end of the new contents. 


The default type of files created by Smalltalk is TEXT. This means that they can be read 
by MacWrite as text-only. If you wish to give other properties to a file, you can use the 
method setType:creator: to do so, following the general approach used in 
MacFileStream typeTEXT. If you wish to write formatted text that can be read by 
MacWrite, you will have to implement the MacWrite document format which is fairly 
complex. Please let us know if you do it. 


Further information about the interface to the Macintosh file system appears in the appendix 
Using the Volume Oriented File Package. 


Alpha Draft i 54 5/30/86 


Smalltalk-80 for the Macintosh 
The Macintosh ToolBox 


This version of Smalltalk includes an interface to the Macintosh ToolBox routines. You 
can call any Macintosh ToolBox routine as long as the routine has a trap number (some do 
not and so must be reimplemented in Smalltalk, which we have not done yet) and its 
arguments are simple enough. The message is constructed as follows: 
the receiver is Mac, the sole instance of class Macintosh, 
the first keyword is the name of the routine 
followed by the first argument; 
each additional keyword is the formal name of its argument 
followed by the argument itself. 
Examples are: 


Mac penNormal. 
Mac textSize: 14. 
Mac offsetRect: someRect dx: 22 dy: -33. 


A nearly complete exercise of the QuickDraw routines can be found in 
TooiBox-Support>Macintosh>quickdraw sample>drawStuff 

and the routines which it calls. A complete description of the ToolBox interface can be 

found in the appendix Smalltalk ToolBox Access. 
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Known Bugs 


If you collapse the Transcript, or have multiple views open on it (we haven't tracked down 
the details), Transcript operations occasionally fail or get hung in a loop. In case of such a 
failure, it should suffice to interrupt with Apple-period, then execute Transcript clear in 
some other window. 


The Smalltalk simulator, which is used for step and send in the debugger, is incapable of 
single-stepping through process-switching operations such as Processor yield. Try to 
be aware of this situation, as it will crash in a way that can be cured only by rebooting. 


The error message ‘Error opening or reading image’ is unclear. It can mean any of several 
things: 


You accidentally opened the Smalltalk interpreter instead of an image. This causes Smalltalk to look for an 
image named 'Smalltaik-80.image’, which causes an error if that image is not found. 


There was insufficient memory available to load this image. This can be due to the presence of a debugger 
or ram-resident operating system patches which reduce the space available to applications. It could also 
happen if the image had been run on a larger machine in which it had room to grow larger than the limits of 
the current machine. 


Smalltalk was unable to locate the image due to naming conventions in an unusual file system. For 
instance, this version of Smalltalk does not deal with nested file groups. Try putting all your Smalltalk 
files at the top level of the file system. 

There was an actual I/O error in opening or reading the image. 


The message position:, sent to a MacFileStream, will not extend a file beyond its current 
size. To grow a file, you must actually write data, as with nextPutAll:. 
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About this Version of Smalltalk-80 


This version of the Smalltalk-80 system, known as version 1, was licensed from the 
Xerox Corporation as part of an early collaboration on Smalltalk development. Since that 
time, Xerox has made changes and additions to their version which they now offer for 
general licensing as version 2. While there are several differences between these two 
versions, the language is nearly identical, and most of the kernel programming tools 
operate similarly. The principal features of version 2 that are not supported in this release 
include: 

Multiple Inheritance support (not actually used in version 2) 

Sticky browser selections 

Changes file browser 

"Pluggable” viewing protocol 


Some of our customers already have a license for the Xerox version 2 image. It would be 
nice if this image could be adapted to run on the Apple interpreter so that there would be 
complete compatibility between Smalltalks on different machines within such 
organizations. If you are such a customer, you should at least let us know that you want 
such an image. More importantly, if you would like to make it happen, write us a letter to 
that effect. We are prepared to furnish the information you would need to produce such an 
image. This could make an interesting student project, and the result would be a valuable 
contribution to the Smalltalk-80 community. The current Xerox licensing policy provides 
te distribution of such a modified image among others who have purchased a Xerox 
icense. 


*** [ MORE MATERIAL IS TO BE DRAFTED - Pending Inputs ] *** 
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Using the Hierarchial File System 
[ TO BE DRAFTED - Pending Inputs ] 
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Glossary of Smalltalk Terminology 


-A- 


Assignment Statement - A line of code in the Smalltalk-80 language that gives a 
specific value to a variable. The form is: <variable name> left arrow <value>. 


-B- 


Bag - A type of Collection with unordered elements, of which duplicates are allowed. 
(See Set) 


Block - An object that represents a deferred sequence of actions. Blocks are used to 
implement control structures in the Smalltalk-80 system. (see Conditional Selection, 
Conditional Repetition) 


Blue Button: The Blue Button menu is obtained by clicking in the window ttle tabs. 
Alternatively, you can use the Enter key as a shift, which turns the mouse button into Blue 
Button regardless of where the cursor is. The Blue Button can be used to get options 
within a workspace or other view such as "collapse" or "close." 


Buttons - The mouse controls on a Smalltalk-80 system that allow selecting data and 
commands in a visual interaction with the screen. The original Xerox Smalltalk systems 
had mice with three buttons, which were called Red Button, Yellow Button and Blue 
Button, 


-C- 


Class - An object that describes the private memory, methods and messages shared by a 
set of similar objects. (See Object, System Class) 


Class Variable - A variable shared by all the instances of a given class. (See Global 
Variable, Instance Variable, Pool Variable) 


Collection - A Collection represents a group of objects, called its elements. Collections 
provide basic data structures for programming in Smaltalk-80. Smalltalk provides a 
protocol shared by all collections. 


Collection Class - There are several basic subclasses of collections, of which some are: 
Array (including subclass String), Bag, Set, and Sequenceable Collection. (Subclasses of 
the latter type include Ordered Collections, Linked Lists and Sorted Collections.) 


Conditional Repetition - A control structure implemented with blocks similar to an If- 
Then-Else construct in Pascal or Algol. 


Conditional Selection - A control structure implemented with blocks similar to a While 
construct in Pascal or Algol. 
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-D- 

Dictionary - A basic Smalltalk class that represents a set of associations between keys 
and values. 

-G- 

Global Variable - A variable shared by all instances of all classes. (See Class Variable, 
Instance Variable, Pool Variable) 

-I. 

Implementation Description - The definition of a complete implementation, consisting 
of a Class Name, a declaration of Variables available to the Instances, and the Methods 
used by the instances to respond to Messages. 

Interface - The set of messages to which an object responds. 

Instance - A particular one of the objects described by a class. (See Object, Class) 
Instance Variable - A variable used only by a particular object throughout its lifetime. 
(See Global Variable, Class Variable, Pool Variable) 

-M. 

Message - A request sent to an object requesting that it perform one of its operations. The 
sender of the message is also an object. (See Object, Method, Receiver, Protocol 
Description) 


Message Argument - A part of a message supplying further information needed by the 
operation. 


Message Categories - A grouping for messages that invoke similar operations. 


Message Pattern - The description of a message contained in a Protocol Description for a 
class. A Message Pattern consists of a message selector and a set of argument names. 


Message Selector - The name of the type of operation requested by a message. 
Method - Specification of an operation to be carried out by an object. The Smalltalk 
concept of method is similar to a "procedure" or "function" in Pascal. (See Object) 

-0- 

Object - An object is composed of some private memory and a set of operations. 
Objects are the most fundamental parts of Smalltalk. Complex objects can be built from 


simple objects. An object might represent a number, a data structure, a program, etc. (See 
Class) 
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-P. 


Pool Variable - A variable shared by all instances of a specific subset of all classes. 
(See Global Variable, Instance Variable, Class Variable) 


Primitive Method - An operation performed in the machine language of the host 
machine. Unlike most of the Smalltalk system, it is not written in the Smalltalk language. 
(See Method) 


Private Variable - A variable available only to a single object. (Instance Variables are 
private.) The name for such a variable must start with a lower-case letter. 


Protocol Description - A list of the messages (in the form of Message Patterns) 
understood by instances of a given class. 


Pseudo Variable Name - An identifier that refers to an object. Unlike a variable, a 
pseudo-variable cannot be changed with an assignment statement. Examples of pseudo- 
variables: Nil, True, False, Self. 


-R. 
Receiver - The object to which a message is sent. 


Red Button - There were three different mouse buttons on the original Smalltalk 
systems, and using each caused a different kind of menu to appear. The Red Button is 
used to size a new workspace and also functions to select text within any view. 


Gi 


Self - A pseudo variable used in a method that refers to the object that receives the 
message. 


Sequenceable Collection - One of the basic Smalltalk-80 Collection Classes, which 
represents collections whose elements are ordered and are externally named by inte ger 
indices. Subclasses of Sequenceable Collections are Ordered Collections, Linked Lists 
and Mapped Collections. 


Set - In Smalltalk, a Set is a Collection with unordered elements, of which duplicates are 
not allowed. 


Stream - A Collection Class which provides the mechanisms for storing and accessing 
objects together as linear and nonlinear groups. Class Stream also represents the ability to 
maintain a position reference into a collection of objects. (This is called streaming over a 
collection.) 


System Class - Those classes inherent in the Smalltalk-80 that provide the functionality 
of a programming language and environment. System Classes are in the categories of 
Arithmetic, Data Structures, Control Structures, etc. (See Class) 


-V. 
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Variable - An item of information available to the methods in an object or class. There are 
five different kinds of variables: Instance, Temporary, Class, Global and Pool. These 
vary in the scope of knowledge of and access to the variable. Variables can have names 
composed of a sequence of letters and numbers (must begin with a letter). A variable is 
given a value with an Assignment Statement. (See Private Variable, etc.) 


-Y- 


Yellow Button - There were three different mouse buttons on the original Smalltalk 
systems, and using each caused a different kind of menu to appear. Clicking the mouse 
button in the gray area corresponds to the old “Yellow Button". The Yellow Button is also 
used to get a menu for editing the contents of a view, by clicking on the right edge of a 
scroll bar, or using the Option key as a shift to make an ordinary mouse click a Yellow 
Button. 
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Appendix 1 


Using the Volume Oriented File 
Package 


The Volume Oriented File Package that is in the latest release of Smalltalk (June 18th image 
and beyond) is slightly different than the previous file package that Smalltalk used. 
Highlights are multiple volume support, source and changes file hunting, user aliases, and 
user defaults. 


The Basics 


Disk and Diskette no longer exist. The most common operations on files can be 
translated to the new system as follows: 


Old File Package New File Package 

Disk file: 'foo' FileStream fileNamed: ‘foo' 

Disk oldFile: 'foo' FileStream oldFileNamed: ‘foo’ 
Disk newFile: ‘foo’ FileStream newFileNamed: ‘foo’ 
Disk filesMatching: '*.st' FileDirectory filesMatching: '*.st' 


All file names are of the format: <volume prefix>:<name>. The volume prefix and 
colon may be left off to access the default volume (see below for more on the default 
volume). Valid volume prefixes are Internal, External, MacDefault, and the names of 
whatever volumes are mounted. In addition, ? may be used as a volume prefix to get a 
menu of all volume prefixes to choose from. 


New volume prefixes may be aliased to existing volumes via the message alias:to: sent to 
FileDirectory. For instance FileDirectory alias: 'Diskette' to: ‘Internal’ will set 
up Diskette to be a valid volume prefix referring to the same volume as prefix Internal 
does. Note that there is no difference between an alias and the original volume prefix 
however, aliasing is not transitive (i.e. if you alias a to b, then b toc, a is now different 
from b and c). Volume prefixes may be removed with the message unalias: sent to 
FileDirectory. 


The volume prefixes Internal, External, and MacDefault, are initially set up to be the 
internal diskette, the external diskette, and the Macintosh default volume (where the 
Smalltalk application was started from) respectively. These volumes are known as the 
fixed volumes and have some special properties. You of course may alias other prefixes to 
these volumes, and may alias the names to other volumes, however, the properties of bein g 
fixed volumes stays with the volumes, not the prefixes. 


Any volume may be made to be the Smalltalk default volume, which is used when no 
volume prefix is specified. This can be done by sending default: to FileDirectory. For 


Alpha Draft 65 5/30/86 


Smalltalk-80 for the Macintosh 


instance FileDirectory default: ‘External’ sets the default to be the external drive. 
The default is just like an alias, and so if you re-alias the volume prefix, the default will not 
have changed. Do not confuse the Smalltalk default with the Macintosh default volume 

x (which MacDefauit is initially a volume prefix for), they have no connection to each 
other. However, one can make the Smalltalk default the same as the Macintosh default 
with the expression: FileDirectory default: 'MacDefault' which is how the system is 
initially set up. Finally, you can have no default by sending the message noDefault to 
FileDirectory which cause the system to ask you to choose a volume every time you do 
not include a volume prefix in a file name. 


When the system starts up it aliases all mounted volumes using their names as volume 
prefixes (so you can use the name of a volume directly). As you execute if new volumes 
become known (via inserting a diskette for example) then they will be aliased in the same 
way. To eject a disk, choose eject from the screen menu, and then select the volume you 
want to eject from the pop up menu that appears. Ejecting now merely places the volume 
off-line (it used to unmount it) and so files may be still open on an ejected disk. Upon 
shutdown, all volumes are flushed and all but the fixed volumes are forgotten. In the 
process, all files that were open on forgotten volumes are closed and placed in a state such 
that further activity on them will fail. Files on fixed volumes will be re-opened when the 
system comes up (if still referenced) but no check will be made to see if it is really the same 
volume. 


The Frills 


Smalltalk will now hunt for the sources and changes files when it starts up. The name of 
the changes file is taken to be the same as the image file with .image stripped off (if it's 
there) and .changes tacked on. Note that the system forms the name at startup and so you 
can rename your image from the Finder so long as you rename the changes file too. 
Furthermore, you can now have multiple images on you disks. If you double click on an 
image, then it will be opened by Smalltalk If you just double click on Smalltalk then it 
will try to open an image named Smalltalk-80.image and bomb if it isn't there. 


The changes file and sources files have now been untied. Now you can have one without 
the other. Hence, never set SourceFiles to nil if you want to run without sources 
(occasionally useful), do SourceFiles ~ Array new: 2 instead. Furthermore, unlike 
before, the system will try to find the sources and changes each time you startup (before, 
once you ran without them, you had to manually reinstate them). 


The Guts 


The following messages can be sent to class FileDirectory. They cover all of the old 
functions that were performed by Disk and then some. 


aliasesDo: enumerate all the associations between 
volume prefixes and actual volumes 
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checkName:fixErrors: check the first argument as a legal file 
name if it is answer it, if isn't and the second argument is true answer a fixed-up 
version of the name, else error 


convertName:to: convert the first argument to a volume 
and a file name and then evaluates the second argument with them as the two values 
do: enumerate all volumes, will duplicate 
some, includes the default 

filter With: like do: but replaces each volume with 
the result of the block 

fromUser puts up a menu and lets the user select a 


volume prefix, answers the volume 


isLegalFileName: answers true or false based on whether 
or not its argument is a valid file name 


Much of the pre-existing generic file package was removed (classes File and FilePage for 
Starters) as it was actually quite Xerox specific. As a consequence, adding a another file 
package (in addition to Macintosh files) may be quite difficult if it is lower level than the 
Macintosh file model. However, since I don't see us using another file system with our 
Smalltalk I don't think that this is a big worry (famous last words...) 


Most of the standard Macintosh volume operations have been defined for instances of 
MacVolume. In particular the messages eject, flush, mount, and unmount exist. 
Furthermore close and open exist for compatibility with the abstract Smalltalk model; they 
perform a flush and a getVolInfo respectively. Smalltalk tries to keep you from 
wreaking havoc on the Macintosh file system, but is easy to get around. For instance never 
unmount the Macintosh startup volume (go on, make my day...). 
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Appendix 2 


Smalltalk ToolBox 
Interface Details 


General Comments about Smalltalk Toolbox access 


Within class Macintosh in your standard Image there are several method categories of 
interest. Category globais contains methods to access various quickdraw globals. 
Category quickdraw calls contains the calls we thought should be implemented using 
primitive 160 to make them a little faster. The category quickdraw sample contains a 
sample program that does various things with quickdraw. This is a good sample program 
for you to see how to use the Toolbox using Smalltalk. To run it, execute Mac 
drawStuff. The memory inspect category contains a method, d0Result, that allows you 
to see what the DO result was after a Toolbox call that returns result information in DO. 
There are also methods in memory inspect for looking at any particular memory location. 


If you need to define some additional PascalRecords, look at the existing definitions within 
GRE eee to oulber SopRor to see how to deal with things like nested Pascal 
RECORDS. 


There are 8 types of data currently being passed between SmallTalk and the Toolbox. They 
are Integer, Longint, Boolean, Point, Rectangle, String, Pointer and Handle. Each of 
these types is stored in Smalltalk format while using it within Smalltalk code, then it is 
converted to Pascal format within a call to the Toolbox. Pointers and Handles are stored 
within a Smalltalk class called PascalRecord. The PascalRecord class was created 
specifically to deal with Pascal RECORDs and other pieces of Toolbox data that are 
accessed by either a pointer or a handle. More details on PascalRecords later. Within the 
Toolbox interpreter there are 16 low level routines to deal with conversion (both ways) of 
these 8 data types. These routines are called from Primitives 160, 161 and 162 through 

` groups of intermediate level routines that set things up for the low level conversion routines 
to handle. 


Primitive 160 is used by defining a method within Smalltalk for each Toolbox procedure 
you want to call. This method contains parameter information in its literal frame. There are 
a few methods defined in this way in the quickdraw calls category of class Macintosh in 
your image. If you haven't defined a Toolbox call using primitive 160, then primitive 162 
is called automatically through the doesNotUnderstand method of class Macintosh. It 
looks up the name of the method in a table of Toolbox calls where it then gets the correct 
parameter information for the call. The lookup uses only the first 8 characters of the name 
and ignores case. Once they obtain parameter information, both primitive 160 and 
primitive 162 call a interpreter routine ‘CallTraps' to do the actual data conversion and 
perform the call. For Toolbox calls that you use very frequently, you may want to use 
primitive 160 since it is slightly faster. Most Toolbox calls will work fine already though 
using primitive 162 and that is what we recommend for probably 90% of the calls. 
Primitive 160 uses more space than primitive 162 so use it sparingly. 
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There may be some errors in the table used by primitive 162. If you have problems with 
any Toolbox call that uses primitive 162, implement the call yourself with primitive 160 
then please let us know about the problem! You also need to know that currently Smalltalk 
can only access Toolbox calls that are made through traps. This includes all of Quickdraw 
and most of the Toolbox calls. You may find a few that won't work though. These will be 
available in a future release! 


Primitive 161 (used to read from and store into the fields of 
Pascal records) 


A PascalRecord in Smalltalk has three fields: 
handle <LargeInteger> 
pointer <LargeInteger> 
bits <ByteArray>. 


In this memo, PascalRecord means one of these above Smalltalk objects but Pascal 
RECORD means a Pascal format piece of memory used to store Pascal format fields. 
This is usually associated with a Pascal RECORD TYPE definition. There should be a 
subclass of PascalRecord defined in SmallTalk for each type of Toolbox Pascal RECORD 
you need to access. For example: BitMap, GrafPort, Region, etc. A PascalRecord should 
be in only one of these four states: 
1. handle = Nil, pointer = Nil, bits = Nil. (no space allocated for this record) 
2. pointer = a SmallPositiveInteger or LargePositiveInteger, handle = Nil, 
bits = Nil. (data space for this record is in a fixed location within a Toolbox heap) 
3. handle =.a SmallInteger or LargePositivelnteger, 
pointer = Nil, bits = Nil. (data space for this record is in a relocatable 
location within a Toolbox heap) 
4. bits = a Smalltalk ByteArray containing an even number of bytes, 
pointer = Nil, handle = Nil. (data space for this record is in a 
relocatable location within the Smalltalk heap) 


From one of these states, the conversion routines produce the correct information for 
Pascal as follows: 


Conversion to a Pascal pointer: 
if handle ~= nil then follow it and pass the pointer 
if pointer ~= nil, then pass the pointer 
if bits ~= nil, pass the address of the bits within the ByteArray, 
offset to skip ST's length and class fields 
otherwise return a primitive error 


Conversion to a Pascal handle: 
if handle ~= nil then pass it 
if pointer ~= nil, then create a handle on the stack and pass it 
it bits ~= nil, create a handle and pointer on the stack pointing the 
the address of the bits within the ByteArray and pass it 
otherwise return a primitive error 


Here is an example of how we use PascalRecords and primitive 161. If we want Smalltalk 


to be able to read and write the portRect field of grafports, we would define the following 
two methods in class GrafPort: (GrafPort being a subclass of PascalRecord) 
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portRect 
"Pascal = È rect := aPort.portRect;" 
“primitive: 161 recordoffset: 16 type: 'R'> 
# self primitiveFailed 
portRect: rect 
"Pascal = aPort.portRect := rect;" 
<primitive: 161 recordoffset: 16 type: 'R'> 
# self primitiveFailed 


This tells primitive 161 that at offset 16 (bytes) within self (the Pascal RECORD pointed to 
by the PascalRecord parameter on the Smalltalk stack) there is a rectangle field. If there are 
two parameters (portRect: rect) the primitive knows it is a write. It then converts the 
SmallTalk format rectangle on the top of the Smalltalk stack into an 8 byte Pascal format 
rectangle and stores this at offset 16 within the Pascal RECORD. If there is only one 

parameter, primitive 161 converts the rectangle at offset 16 from a Pascal format rectangle 
into a Smalltalk format rectangle which it passes back on the Smalltalk stack. 


Here is a table of the 8 types of data that can be passed in the Type Descriptor field to 
primitives 161 and 160. In the case of primitive 161, there will only be one parameter 
described in the Type Descriptor field. As you will see below, primitive 160 has one 
type for each parameter in a particular Toolbox call. 


type code Toolbox Type ST class (data formats are different) 
Integer SmallInteger, LargeInteger up to 16 bits 
Longint SmallInteger, LargeInteger up to 32 bits 
Boolean Boolean 

Point Point 

Rectangle Rectangle 

String String. 

Pointer PascalRecord (think g for direct pointer) 
Handle PascalRecord 


TUUMD'UVWT 


(used to call Toolbox register or stack based 
routines through the Toolbox Trap mechanism) 


Here is some sample code to create a grafport, use it to frame a rectangle, and release the 
port. Mac is a Smalltalk object of class Macintosh which implements Macintosh Toolbox 
methods by calling primitive 160 with the correct Trap number and Parameter types as 
arguments. The Smalltalk code: 


| port oldPort | 
oldPort © Mac getPort. 
port ©“ GrafPort newM. "newM for data on the Mac heap, newS for 
data-on 
the Smalltalk heap” 
Mac openPort: port. 
Mac setPort: port. 
Mac frameRect: (10@20 rect: 1008100), 
Mac setPort: oldPort. 
Mac closePort: port. 


You do not really need to understand how to set up calls to primitive 160 since primitive 
162 already has a table containing parameter information for all the Toolbox traps. This 
documentation is only provided in case you want to speed up a few of the calls you use 
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over and over again within a loop. Here are some of the methods in class Macintosh which 
get called in the above exampie: 


getPort š 
"Pascal = PROCEDURE GetPort (VAR gp: GrafPtr);" 
<primitive: 160 trapA: 16rC74 type: '--VD'> 
“trap number" "no function, ignore receiver, VAR 
pointer" * self primitiveFailed 





openPort: port 
"Pascal = PROCEDURE OpenPort (gp: GrafPtr);" 
<primitive: 160 trapA: l6rC6F type: '=-D'> 
"trap number" "no function, ignore receiver, 
pointer" # self primitiveFailed 


frameRect: rect 
"Pascal « PROCEDURE FrameRect (r: Rect);" 
<primitive: 160 trapA: 16rCA1 type: '=--R'> 
"trap number” "no function, ignore receiver, 
rectangle” # self primitiveFailed 


closePort: port 
"pascal = PROCEDURE ClosePort (gp: GrafPtr);" 
<primitive: 160 txapA: 16rC7D type: '--D'> 
“trap number" "no function, ignore receiver, 
pointer” * self primitiveFailed 


Type Descriptor (Type) Details: 


For primitive 160, the Type Descriptor parameter describes the same type codes as 
listed in the table within the primitive 161 description above. 


When a type code character represents a VAR parameter, precede it by the character ‘V’, 


When a parameter is passed in a register to a Toolbox routine instead of on the stack, the 
Type Descriptor string has to let primitive 160 know about this. The Toolbox uses three 
registers (DO, Al and AQ) to pass and return parameters. In the Type Descriptor string, the 
register codes are: 


DO ='0' 
Al='"V 
AO = '2' 


The register code character optionally follows the normal type code character. 
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Unlike primitive 161 which always expects a Type Descriptor string of length 1, 
primitive 160 expects a Type Descriptor string of the following format: i 


<Type Descriptor> = <function result type><receiver type><parameter 





info> 
<result type> = type code or '-' if not a function. 
The 
code character can optionally be followed 
by a 
register code if the function result is 
passed back from the Toolbox in a 
register. 
<receiver type> type code of receiver if receiver is 
used as a parameter or '-' if receiver is ignored. 
<parameter info> aetype code character for each 
parameter 
other than the receiver. Each type code 
character is preceded by a 'V' if that 
parameter is a VAR parameter. Each 
type code character can optionally be 
followed 
by a register code if the parameter is 
passed to the Toolbox in a register. 
Nothing 
if there are no parameters. 
More examples: 
globalToLocal: pt 
"Pascal = PROCEDURE GlobalToLocal (VAR pt: 
Point);" È 
<primitive: 160 trapA: 16rC71 type: '--vD'> 
"trap number" "no function, ignore receiver, 
VAR point" # self primitiveFailed 
sectRect: srcRectA srcRectB: srcRectB dstRect: dstRect 
"Pascal = FUNCTION SectRect (srcRectA, srcRectB: Rect; 
VAR dstRect: Rect): BOOLEAN;” 
<primitive: 160 trapA: 16rCAA type: 'B-RRVR'> 
"trap number" "Boolean function, ignore 
receiver, 
rect, rect, VAR rect" + self 
primitiveFailed 
newPtr 
"Pascal = FUNCTION newPtr (logicalSize: 


Size): Ptr;" 
<primitive: 160 trapA: 16r01E type: 'D2-L0'> "trap number" 
"pointer function result in A0, ignore receiver, longint 
input 
param in DO“ + self primitiveFailed 


The conversion routines check the type of each argument passed on the Smalltalk stack 
against the Type Descriptor information in the call to primitive 160 or 162. A primitive 
failure is flagged if there is a type mismatch. The interpreter routine CallTraps then 
converts each value appropriately and calls the designated trap. 
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Consider the case of SetPt (VAR pt: Point; h, v: INTEGER) which could become: 


setPt: pt h: hv: v 


"Pascal = PROCEDURE SetPt (VAR pt: Point; h,v: 
INTEGER) ;" 
<primitive: 160 trapA: 16rC80 type: '--VPII‘'> 
"trap number" "no function, ignore receiver, VAR 
point, 


integer, integer" * self primitiveFailed 


In this case point does not need to have valid field values on input. The Smalltalk object 
passed in must be a Smalltalk point. It would be OK here though if this point were created 
by the Smalltalk statement ‘Point new'. This statement creates a point whose fields are 
both NIL. When they get Var parameters with NIL fields, the conversion routines pass 
zero as the input values to the Toolbox. The retum values from the Toolbox call are then 
copied into the fields of the point parameter. 


The Toolbox routine setPt could optionally be encoded as: 


"point" setx: x y: y 
<primitive: 160 trapA: 16rC80 type: '-VPII'> 
"trap number" "no function, receiver is VAR point, 
integer, integer" # self primitiveFailed 


Here the receiver (hence the comment "point") is also used as the first parameter so we save 
pushing a parameter on the stack. 


Smallintegers and Booleans are not allowed as VAR parameters. For LargeIntegers and 
Strings as VAR parameters, the input object is converted into the result object via a 
Become. For Points, Rectangles, and PascalRecords, the new values for the appropriate 
pointer fields are substituted within the original object. 


When using data in this Smalltalk/Toolbox environment, you must not pass the Toolbox 
the address (pointer or handle) of any data stored in the Smalltalk heap if the Toolbox is 
going to remember that address after it returns from that one call. It is not possible for the 
location of a Smalltalk ByteArray object to change during the time a single Toolbox call is 
Tunning. It can change between calls, however; so ByteArrays should only be used for 
data whose address is passed to the Toolbox every time the Toolbox uses the data. This 
way the conversion routines will create the correct address each time. 


In both primitives, the ‘primitive: <160 or 161>' part is optional. For example, primitive 
160 can be called by 

<trapA: 16rC71 type: '--VP'> 
and primitive 161 can be called by 

<recordOffset: 16 type: 'I'>. 
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A Summary of Useful Expressions 
from the Level 1 System Workspace 


Changes 


Smalitalk noChanges. 
Resets the set of changes to be empty. 
Form removeFromChanges. 
Removes ail changes in class Form from the changes set. 
Smalltalk changes asSortedCollection 
printit to see a list of ail changes in the changes set. 
Smalitalk browseChangedMessages. 
Opens a message browser on all methods in the changes set. 
(FileStream fileNamed: 'Changes.st') fileOutChanges. 
Writes a file of all changes in the changes set. 
FileStream fileNamed: 'PenChanges.st') fileOutChangesFor: Pen. 
Writes a file of all changes for ciass Pen in the changes set. 
(FileStream oidFileNamed: ' Changes.st') fileIn. 
Reads in changes from the file 'Changes.st 


Files 


* (FileStrcam fileNamed: 'Hello') edit. 
Opens a file edit window on the file ‘hello’. 
FileDirec.ory filesMatching: '*.st' 
Printit to view file names. It is actually more convenient 
to open a file list and type *.st<Return» in the top pane. 


Inquiry 


InputState browseAllAccessesTo: ‘deltaTime’. 
Like ‘inst var refs‘ in the browser. 

Smalltalk browseAllCallsOn: #isEmpty. 
Like ‘senders’ in the browser. 

Smalitalk browseAllCallsOn: #showWhile: and: #read. 
Browses methods which send both these messages. 

Smalltalk browseAlllmplementorsOf: #includes: 
Like ‘impiementors' in the browser. 

Smalitalk browseAllCailsOn: (Smailtalk associationAt: #Mac). 
Browse ail references to a global variable 
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Smalltalk browseAllCallsOn: (Cursor classPool associationAt: #ReadCursor). 
Browse all references to a class variable 
Smalltalk browseAllCallsOn: (Undeclared associationAt: #Disk) 
Browse all references to an undeclared variable 
Smalltalk browseAllMethodsinCategory: #examples 
The name says it all, 
Smalltalk browseAliSelect: [:m | m isQuick]. 
{hackers} Browse all methods for which the block is true. 
Smalltalk browse: Pen 
Open a browser on the class Pen 
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Enumeration 


Smalltalk printSpaceAnalysis 
Creates a text file listing number of objects and words of space 
used by the code of each class and by the instances of that class. 
Smalitaik garbageCollect. 
Force Smaiitalk to do a full garbage collection. 
Use before the following enumerations... 
FileStream instanceCount 
Printit to find out how many there are currently 
StrikeFont allinstances inspect. 
inspect an array of all instances of this class. 
(Smalltalk collectPointersTo: StrikeFont somelnstance) inspect. 
Opens an inspector on all objects which point to one of the fonts. 


Undeclared Variables Dictionary 


Undeclared keys 
printit to see names of any undeclared variables. 
Undeclared inspect 
Nicer way to view undeclared variables if you're in Level 1 
or if you've filed in Dictionaryinspectors 
Undeclared ~ Dictionary new. 
Resets the dictionary of undeclared variables. Note this will 
preclude your being able to find the methods in which they occur. 
Undeclared associationsDo: [:assn | Smalltalk browseAllCallsOn: assn] 
Browses all references to the first undeclared variable encountered. 


Dependents Dictionary 


(Object classPool at: #DependentsFields) keys 
printit to see what is in the global dependents dictionary 

(Object classPool at: #DependentsFields) keysDo: 
[:each | (each isKindOf: DisplayText) ifTrue: [each release]] 
Releases certain objects from the dependents dictionary. 


Housekeeping 


Transcript clear. 
Resets the transcript window. 
Smalltalk allBehaviorsDo: 
[:class | class removeSelector: #Dolt; removeSelector: #Doltin:]. 
Removes methods generated by dolt and printit. 
Smalltalk removeKey: #GlobalName. 
Removes a symbol from the global dictionary. You should check first 
that there are no outstanding references to it. 
Smalltalk declare: #GlobalName from: Undeclared. 
Will make GlobaiName be a new global variable. If it was formerly 
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in Undeicared, then all references to it will be forwarded to the 
new global variable. This is how forward references are handled in fileins. 
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SourceFiles ~ Array 
with: (FileStream oldFileNamed: Smalltalk sourcesName) readOnly 
with: (FileStream oldFileNamed: Smailtalk changesName). 
Establishes source and changes files. 

SourceFiles do: [:x | x close]. 
Closes source and changes files. 


SourceFiles ~ Array new: 2. 

Causes Smalltalk to run with no source or changes files VEC retrieve.st will still work). | 
Smalltalk condenseChanges 

Copy all methods in the changes file to a new file, and then replace 

the current changes file by the new one. in the process, multiple 

copies of method definitions and other unnecessary text is removed. 

This process may take a long time, and will require sufficient disk 

space for both copies of the file during the process. You should make 

backup copies of your image and changes before running this method. . 


Measurements 


Smalltalk spaceLeft 
printit to see how much space is currently available. 
Symbol instanceCount 
printit to see how many Symbols are in use 
Symbol rehash. 
Purge any Symbols which are no longer in use. 
Time millisecondsToRun: [ Pen example ] 
printit to see how long it takes to execute the block. 
MessageTally spyOn: [Pen example]. i 
(Level 1 only) Presents an time-use profile for execution of the block. 


Crash recovery 


Smalltalk recover: 5000. 
Opens a window on the last 5000 characters added to the changes file 
ScheduledControllers removeAndUnschedule: <someController> 
Execute this from a debugger if a window gets scheduled which is 
incapable of responding properly to all window protocol. 
You'll have to poke around until you find the top-level controller, 
and then type an expression that refers to it in place of <someController> 
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Appendix 4 
Sample Smalltalk Files 


Included with your Smalltalk system are several Smalltalk files ("goodies") which add 
interesting or useful capability to your Smalltalk. Execute (FileStream oldFileNamed: 
'filename.st') fileIn to read any of the sample files into your system. The file names 
are not case-sensitive, but spaces are significant. The .st naming is only a convention - it 
makes it easy to browse all Smalltalk files using *.st in the top pane of a file list. 


Printing.st includes a definition for MacPrintStream. This supports access to an 
Apple Imagewriter connected to the printer port. It also adds a menu option for printing 
most windows. Printing from the window title menu produces a bitmap of the window in 
question. Printing from a text pane menu produces text with an attempt to support the 
unusual Smalltalk characters. The class method examples includes an expression for 
printing the bits of an arbitrary screen rectangle. Some such bitmaps will be too wide for 
the printer; use a wide-carriage printer, or figure out how to print landscape bitmaps 
(actually easier than the portrait format supported by MacPrintStream). Imbedded in this 
file is a method for rotating bitmaps by 90 degrees, which might be otherwise useful. 


FET.st defines a class which will perform a one-dimensional complex Fast Fourier 
Transform of data held in Smalltalk arrays. The example method test illustrates the use of 
this capability. This code computes a complex Fourier transform; what many people 
expect is a "power spectrum" which can be derived by summing the squares of 
corresponding real and imaginary components. 


Fractal.st contains code for producing three-dimensional surfaces based on fractal 
geometry. Execute Fractal example for an example. 


Toothpaste,st alows one to draw shaded worm-like curves on the screen using a "brush" 
that looks like a highlighted sphere. Execute Form toothpaste: 30 and then paint with 
the cursor. Use option-click to stop. 


Web,st is another cute drawing program. It uses a model which lags behind the current 
mouse position, and then draws lines between the lagging cursor and the current cursor. 
Execute QDPen new web and then draw with the mouse. Click to erase the screen, and 
option-click to stop. 


Macintosh-quickdraw.st is a full set of QuickDraw call definitions. This makes all the 
QuickDraw messages visible, which they are not with the current space-saving generic 
lookup mechanism (see appendix). At the cost of some memory space, it thus makes 
QuickDraw messages easier to browse. 


DictionaryInspectors.2.st allows direct access to keys and values when inspecting 


dictionaries. This goodie has already been included in the Level 1 image. 


MacPaint.st defines a method which will create a graphics file readable by MacPaint. 
The comment at the end of method Form macPaintOn: gives a sample invocation. The 
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method is already included in Level 1, but its example comment is in error. If you fileIn 
this goodie, it will correct the comment. 


RS232.st defines a few methods which support input and output via the two Macintosh 
serial ports. One of these includes a large comment explaining how to set baud rate etc., 


and another is a sample application which downloads text (eg from a lap computer) to a 
Mac file. 


RetrieveSources,st allows access to the full system sources, even if your Macintosh 
does not have a hard disk. If you have browsed to a given method (decompiled), and wish 
to see the full system source (as you would with a hard disk) choose retrieve (a new 
option) from the code pane menu. You will be asked to insert one of the disks with the 
divided source file on it, and then the full code will appear. This technique will fail if you 
happen to choose one of the three methods that straddle breaks between the file divisions. 


DropChanges.st is for the fearless programmer whose .changes file has grown too 
large (even after condensing), yet who still wants to continue making changes. One could, 
of course, simply delete the changes file, but this will prevent the further recording of 
changes. Instead, by executing Smalltalk dropChanges, the current source code will 


be discarded (save it first, if you care), but the change file will continue to record further 
development. 
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Smalltalk-80 for the Macintosh is Apple’s enhanced version of the _ 
Smalltalk-80™ programming language and environment for the =~ 
Macintosh™ computer, based on Xerox Smalltalk-80 Version I. It is 
intended primarily as a tool for learning and experimentation, but 
can also serve as a useful development environment in which to 
build prototypes of small to medium-sized applications and 
systems. The turnaround time for program changes is extremely 
rapid, allowing much faster development than with standard 
compiled languages. 


This manual covers only those details specific to the Macintosh 
implementation; it does not attempt to discuss the Smalltalk-30 
language and user interface. If you are not already familiar with 
Smalltalk-80, you can learn more about it by reading the existing 
literature on Smalltalk and object-oriented languages in general. A 
basic bibliography is included in Appendix E. 











About this releasa 


This Macintosh Plus release (version 0.3) of the Smalltaik-80 
programming system is the latest of several unsupported versions oi 
Smalitalk-80 released by Apple Computer, Inc., in the hope of 
allowing interested parties to get “hands-on” experience with 
Smalltalk. This release is in:ended to improve the earlier version 
0.2 release of Smalltalk-80 for the Macintosh (August 1985). IL 
generally conforms to the Xerox user interface for Smalltalk-80 but 
deviates in many ways from the standard Macintosh user interface. 


Version 0.3 is intended to run on a Macintosh Plus with a minimum 
of one megabyte of memory and at least one 3.5-inch disk drive. It 
can also run on a Macintosh XL with one megabyte or more of 
memory, or on other Macintosh computers with third-party 
memory upgrades of one megabyte or more. (Third-party imple- 
mentations must be contiguous and follow Toolbox memory 
organization.) If you have less than one megabyte of memory, you 
should get version 0.2 of Smalltalk-80 for the Macintosh, which 
contains a stripped-down image that will run on 512K machines. 


A hard disk makes the system more usable, but it can be run from 
one or more double-sided 3.5-inch disks. When you are using a 
hard disk, the complete sources to Smalltalk-80 for the Macintosh 
are available on-line. Without a hard disk you can only see 
decompiled sources without comments. 





New features of this release 


New features for this Macintosh Plus version include 
O faster painting and repainting of windows and text 
O Hierarchical File System (HFS) support 


© more complete Macintosh Toolbox access, including Pascal 
record compatibility 


greater compatibility with Xerox Smalltalk-80, Version II 
new and better text-editing facilities 


ag a 0a 


friendlier browser interface 
easier finding of hidden windows 


a n 


better support for change management 

G many bug fixes 

Some features of Smalltalk-80 for the Macintosh carry over from the 
version 0.2 release. For example: 

O Volume management supports many file servers. 


Z Automatic spelling correction is provided for variable and 
message names. 


i 


Multiple images can reside on the same disk. 


fl 


One interpreter works on all machines and uses all availabie 
memory. 


2 Up to 32,000 objects are supported. 
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Here are some additional details of new features. This list will be 
especially meaningful if you have used version 0.2 of Smalltalk-80 
for the Macintosh. 


a 


Window update is much faster, since bitmaps of underlying 
windows are saved. This makes the whole system faster and more 
usable, but it also uses more space. If the system is about to run 
out of space, it will tum off the fast window feature, then notify 
you that space is running low. To tum on the fast window feature 
again, choose fast windows from the system menu. 


The window menu, which is accessed by pressing the mouse 
button in a window title tab, is now also available by using the 
Command key with the mouse, rather than the Enter key as in 
version 0.2. 


You can now run Smalltalk from inside a folder under the 
Hierarchical File System (HFS). The image and changes files 
should be in the same folder. The Smalltalk-80.sources file 
may be either in that folder or in the root directory of the same 
volume. Once Smalltalk is running, you can access any folder on ® 
any disk, using the choose volume command in a file-list 
window (described in Chapter 2). 


If you look at the menus in a browser, you will notice some new 


. entries. The most useful of these is versions. The versions 


O 


O 


command allows you to open a window on the current version of 
a method as well as previous versions still available in the 
changes file. If you change a method, then want to put it back the 
way it was before, use versions. You will also notice that you 
can now rename message categories, classes, and class 
categories from 2 menu. Reazranging or removing class and 
message categories is also easier. 

Version 0.3 contains many new text-editing features, described 
in Chapter 3. 


When you file out a class or class category, you can now also 
optionally file out any shared pools used by that part of the 
system. 


Many other improvements and bug fixes make the system faster 
and easier to use, such as the reorganize command. Most of 
these will be obvious as you use the system. 
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Relation to Xerox Smailtaik-80 


Smalltalk-80 for the Macintosh is based on Xerox Smalltalk-80 
Version I, and was licensed from Xerox Corporation as past of an 
early collaboration on Smalitalk development. Apple has made 
many improvements to it since that time. Xerox has also made 
changes and additions to its version, which it now offers for general 
licensing as Version II. While there are many differences between 
Smalltalk-80 for the Macintosh and Xerox Smalltalk-80 Version II, 
the Smalltalk language is still compatible and most of the kernel 
programming tools operate similarly. 











Support 


This manual should provide you with enough information to get 
started. To work most effectively with Smalltaik-80 for the 
Macintosh, you will need further documentation not provided by 
Apple; see Appendix E, “Bibliography of Smalltalk Literature.” 


Courses and training materials relating to Smalitaik-80 are available 
from PPI, an organization that offers general training in object- 
oriented programming as well as specific courses on Smalltalk-80. 
For further information, contact 


Productivity Products International 
27 Gien Road 

Sandy Hook, Connecticut 06482 
(203) 426-1875 


Apple Computer, Inc., does not provide support for this pre- 
product release. If you should discover bugs in the documentation 
or in the system itself, your only recourse is to work around them 
yourself. (Even though this is an unsupported product, however, we 
do appreciate feedback and bug reports. Use the bug report form at 
the end of this manual.) If Apple later releases another version of 
Smalltalk-80 for the Macintosh, there is no promise of either an 
upgrade price or a guaranteed code migration path. 
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How to use this manual 


Chapter 1 introduces you to Smalltalk-80 for the Macintosh and 
describes the installation procedures to get you started. Chapter 2 
describes the user interface, with particular attention to the ways in 
which it varies from Xerox Version II. Chapter 3 focuses on the new 
text-editing facilities, and Chapter 4 on backup and change 
management. Chapter 5 covers enhancements relating to the 
Macintosh Plus Hierarchical File System (HFS). Chapter 6 discusses 
Macintosh-specific issues for programmers who want to use the 
Macintosh User Interface Toolbox from within Smalltalk. 


The Appendixes provide detailed technical information for the 
serious programmer. Appendix A summarizes useful expressions 
included in the System Workspace window. Appendix B describes 
the Smalltalk “goodies,” utility and demonstration programs 
distributed with the system. Appendix C discusses various useful 
techniques for memory management and economy. Appendix D 
summarizes known bugs and limitations of this release. Finally, 
Appendix E gives a bibliography of available literature on Smalltalk 
and object-oriented programming in general. 
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installation 


You need a hard disk to run the full configuration of Smalltalk-80 for the Macintosh. 
This allows you to keep all the relevant files immediately available on-line. If you 
don’t have a hard disk, you can run a more limited configuration from one or two 
3.5-inch disk drives, provided that at least one of them is double-sided. This chapter 
gives instructions for setting up Smalltalk in either configuration, depending on the 
hardware you have available. 











Disk contents 


Smalltalk-80 for the Macintosh uses four files: 


O Smalltalk-80.interp contains the low-level Smalltalk-80 interpreter, the 
Smailtalk loader, and method tables for calling the Macintosh Toolbox. 


G Smalltalk-80.sources contains the original source text of the Smalltalk 
system as shipped. 


G Smalitalk-80.image contains the compiled object code for all methods in the 
system, including both those supplied with the release and those that you add or 
modify yourself. 
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Smalltalk-80.changes is a text file containing a record of all your actions as 
you work with the system. 


The interpreter, image, and changes files must always be present for Smalltalk to run. 
The sources file is optional, and you can run the system without it—for instance, if 
you don’t have a hard disk to keep it on. If you're connected to a network, it’s also 
possible to access the sources file from a remote file server: see “Remote Access to 
System Sources,” below. As you interact with Smailtalk, both the image and changes 
files are constantly updated. For instance, when you compile a new method with the 
accept command, its object code is written to the image file, and its source text is 
written to the changes file. The contents of the sources file are never changed. 


When you browse a method, the system looks for the source code first in the changes 
file; if it isn't found there, it’s taken from the sources file instead. If no sources file is 
present, the method's object code is automatically decompiled from the image file. 
This produces readable source code, but with all comments stripped out and with 
artificial variable names (t1, t2, and so on) for all parameters and temporary 
variables. If you want to see the original source code for a particular method, you can 
use the goodie RetrieveSources (described in Appendix D) to read the code 
directly from the 3.5-inch release disks. 
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Installation 


The current release of the system is shipped on seven 3.5-inch Macintosh disks. For 
compatbility with all existing Macintosh hardware, all disks are single-sided. The 
image and sources files are broken up into pieces small enough to fit on the single- 
sided disks; a utility program, DivJoin, is included for reconstituting the complete 
files on a double-sided or hard disk. The contents of the release disks are as follows: 


Disk Name Fllenames 


Smalltalk Disk 1 Smalltalk.changes 
System Folder 
DivJoin 1.0d3 


Smalltalk Disk 2 2.Smalltalk. image 
Smalltalk.interp 
Goodies-Demos folder 


Smalltalk Disk 3 
Smalltalk Disk 4 
Smalltalk Disk 5 
Smalltalk Disk 6 
Smalltalk Disk 7 


.Smalltalk.image 
.Smalltalk-80.sources 
.Smalltalk-80 . S0UFrces 


.Smalltalk-80.scurces 
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.Smalitalk-80.sources 
Goodies-Utilities folder 











Installing Smailtalk with a hard disk 


To run the full configuration of Smalltalk-80 for the Macintosh, your hard disk must 
be capable of holding the following files, plus about 1450K of working space (roughly 
3650K total). 





File size (in K) Filename 





1442 Smalltalk-80.sources 

669.5 Smalltalk.image 

0.5 Smalitalk.changes 

54.5 Smailtalk.interp 

15 DivJoin 1.0d9 (not needed on the hard disk after initial installation) 


The assorted goodies included on the release disks are optional, and total about 97K. 
If you have extra space on your hard disk, you might want to keep backup copies of the 
image and changes files, to avoid having to repeat the full installation procedure the 
next time you want to start from a clean copy of Smalitalk. 


Installing Smalltalk with a hard aisk 


Here is the installation procedure: 


1. Make sure the System file on your hard disk is version 3.2 or later and the Finder 
is version 5.3 or later. (These are the versions shipped with this release.) 


. Create a folder on your hard disk for your Smalltalk files. Copy the application 
DivJoin 1.0d9 (on Smalltalk Disk 1) into this Smalltalk folder. 


. Use DivJoin to join the files 1.Smalltalk-80.sources through 
4.Smalltalk-80.sources (on Smalltalk Disk 4 through Smalltalk Disk 7, 
calling the joined file smalltalk-80.sources. (See “Using DivJoin,” below.) 
Place the joined file in your Smalltalk folder. 


. Copy the files Smalltalk.changes (on Smalltalk Disk 1) and 
Smalltalk.interp (on Smalltalk Disk 2) to your Smalltalk folder. 


. Use Divjoin to join the files 1.Smalitalk.image (on Smalltalk Disk 3 and 
2.Smalltalk.image (on Smalltalk Disk 2), calling the joined file 
Smalltalk.image. Place the joined file in your Smalltalk folder. 


. If you wish, you can now remove DivJoin 1.0d9 from your Smalltalk folder. 


. Move any goodies you wish to use into your Smalltalk folder. (The goodies are 
described in Appendix D.) 

. To start Smalltalk from the Finder, open the Smalltalk. image file either by 
doubie-clicking its icon or by choosing Open from the File menu. It takes about 
half a minute to load the image into memory and initialize the system, after which 
Smalltalk’s startup screen is displayed (If you have more than one version of the 
Smalltalk interpreter on your disk, you must indicate which one to start up. Select 
both Smalltalk .image and the interpreter you want by using the Shift key or by 
dragging a selection rectangle around both icons, then choose Open from the 
File menu or type Command-0. Notice that the interpreter and image files must 
be in the same folder on the disk.) 
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Installing Smalltalk without a hard disk 


The following installation procedure assumes that you have a Macintosh Plus with 
one internal double-sided disk drive and no external drive. (An external drive can 
save you some disk swapping, but the procedure is essentially the same.) You will be 
creating two double-sided disks from the single-sided disks distributed in the release. 
Without a hard disk, you won't be abie to keep the source code of the system on-line; 
instead of reading source text from the disk, Smalltalk will automatically decompile 
each method as you browse it 


To install Smalltalk on double-sided 3.5-inch disks, follow these steps: 
1. Start up the system from release disk Smalltalk Disk 1. 


2. Initialize two new double-sided disks and name them Smailtalk System and 
Smalltalk Work. 
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3. Copy the entire contents of Smalltalk Disk Ito Smalltalk System. Put away 
Smalltalk Disk 1 as a backup, in case you ever need to repeat this installation 
procedure. 


4. Restart the system from the Smalltalk System disk. 
5. Copy the file Smalltalk.interp from Smalltalk Disk 2 onto Smalltalk Work: 
. Eject Smaiitalk System. 
. Insert Smailtaik Work. 
. Eject Smailtaik Work. 
. Insert Smalltalk Disk 2. 
. Copy file Smalltalk.interp onto Smalltalk Work. 
. Eject Smalltalk Work. 
. Insert Smalltalk System. 
6. Install the file Smalltalk.image on the Smalltaik Work disk: 
a. Run DivJoin 1.0d9 from the Smalltalk System disk. 
b. Click the Join button. 
c. Eject Smalltalk System. 
d 
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. Insert Smalltalk Disk 3. 


. Select 1.Smalltalk.image as the file to join and click Open. Smailalk Disk 
3 will be ejected and you will be prompted to insert Smalltalk System. 
Continue to swap these two disks as prompted. 


f. When prompted for the name of the output file, eject Smalltalk System. 
g. Insert Smalltalk Work and click Save. Continue to insert disks as prompted. 


h. When prompted for 2.Smalltalk.image, insert Smalltalk Disk 2. (You may 
need to use Command-Shift-1 to eject the Smailtalk System disk at this point.) 


i. Click Done when you are prompted for 3.Smalltalk.image. (There are only 
two parts to be joined.) Insert the Smalltalk Work disk when prompted. There 
will be a delay while DivJoin writes the joined file to the disk. 


j. The Smalltalk Work disk will be ejected and you will be asked to insert 
Smalitalk System. 


k. A message will appear indicating that the join is complete. Click OK to 
continue. 


I. Exit DivJoin by clicking Quit. 
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7. You are now ready to run Smalltalk: 
a. Start up the system from the Smalltalk System disk. 
b. Eject Smailtaik System. 
c. Insert Smalltalk Work. 
d 


. Double-click on the file Smalltalk. image. Although you'll have to do 
several disk swaps to launch Smalltalk, you generally won't have to swap disks 
once you're running. 
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Remote access to system sources 


Smailtalk always expects the file containing the system source code to be named 
Smalltalk-80.sources. If there is no available file by that name, it will use 
decompilation to display the source code for system methods. If your Macintosh is 
connected to a network, the system sources file can be accessed from a remote file 
server, provided that 


© there is a file server on the network 
© the server is mounted as a volume on your Macintosh 


1 


there is a copy of the file named Smalltalk-80.sources in the root directory 
on the server 


Remote access allows many Macintoshes without hard disks to share the same copy of 
the system source code over the network. 











Using DivJoin 


Included on Smalltalk Disk 1 in this release is a new version of the DivJoin program 
that is easier and more flexible than earlier versions you may have used. Divjoin 
allows you to transport large files via 3.5-inch disks. It divides big files into pieces 
smali enough to be stored on 3.5-inch d' ‘ss, and later rejoins the pieces into a single 
file. DivJoin works only on files with a data fork and no resource fork, such as the 
Smalltalk.image file. 


The new version of DivJoin, version 1.0d9, supersedes all earlier versions. (If in 
doubt, use the Get Info command to look for the version number in the file's 
Finder comment.) Unlike earlier versions, the new DivJoin allows you to go directly 
to and from multiple disks. To supplement the installation procedures given above, 
here are complete instructions on using the new DivJoin program for dividing and 
reconsutuung large Macintosh files. 
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Running DivJoin 


DivJoin begins with a dialog box with buttons labeled Join, Divide, and Quit. The 
dialog box also includes radio buttons for specifying the size of divided files. (These 
buttons don’t apply when you're joining files.) 


Whether you click Divide or Join, you're presented with a Standard File dialog box 
for selecting the file to be divided or the first piece of the divided file to be joined. 
The file lists presented by Standard File are often empty, because files that are 
inappropriate to the selected operation are filtered out Only files large enough to 
need dividing, or named appropriately for joining (pieces starting with 1.), appear. 


Once you’ve selected a file, DivJoin prompts you to insert disks as needed, and 
displays a progress/status dialog as it runs. The progress dialog tells whether you're 
dividing or joining, the name of the composite file, the buffer size (all of available 
memory is used), and what DivJoin is doing at the moment. It also displays a Cancel 
button that you can use to cancel the divide or join operation at any time. A Cancel 
button is also included in each of the dialogs that prompt you to insert disks. 


DivJoin doesn’t eject the disks in both drives when a divide or join operation starts. 
As a result, the disk you want may already be inserted when you're prompted for it 
When that happens, use Command-Shift-1 (for the internal drive) or Command- 
Shift-2 (for the external drive) to eject the disk, then reinsert it. 





Dividing a file 


Here is the procedure for dividing a large file into pieces: 

1. Use the radio buttons to specify whether the file is to be divided onto single- or 
double-sided disks. 

2. Click the Divide button. 

3. Use the Standard File dialog to select the file to be divided. Only files large enough 
to need dividing are listed (those larger than a single- or double-sided disk, 
depending on which radio button you clicked). 

4. Insert disks as prompted for succeeding pieces of the file. 

5. When the operation is finished, you’l!l get an alert saving whether it was 


successfully completed or stopped prematurely (either because of an error or 
because you canceled). 


DivJoin tries to be considerate about the disks you insert and how it formats them. If 
you insert a readable Macintosh disk that already has files on it, or a non-Macintosh 
disk, or a damaged one, you'll get an alert and have a chance to reconsider. If the 
disk is already formatted with the appropriate number of sides, DivJoin skips 
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reformatting it to save time. The only mistake it cannot detect is inserting a double- 
sided disk in a single-sided drive. 





Joining a divided file 


To join the pieces of a divided file, follow these steps: 


1, Click the Join button in the initial dialog box. The radio buttons labeled Size 
of divided files don't apply. 

2. Use the Standard File dialog to select the first piece of the file to be joined. Only 
files with the prefix 1. are listed, since that’s how Divjoin names the first piece of 
divided files. 

3. Use the next Standard File dialog to name the output file and to specify the 
destination disk, then click Save. DivJoin can't tell in advance whether the entire 
file will fit on the destination disk you select, though it does check that at least the 
first piece of the file will fit. 

4, Once the first piece of the file has been read, DivJoin ejects the disk it's on and 
prompts you to insert succeeding ones. Click Done after reading the last piece of 
the file. 

5. If the first piece of the file is on a hard disk, DivJoin looks for succeeding pieces in 
the same folder on the hard disk; it assumes it's finished when there are no more. 


Limitations of DivJoin 1.0d9 

DivJoin 1.0d9 suffers from the following known limitations. If you encounter any 
others, please report them as bugs. 

C A file's resource fork, if any, is not included when you divide the file. 


Z No information about divided files is written with them; data corruption errors, or 
your omission of the last file(s), cannot be detected. 


= VO errors are displayed numerically. (See the result codes in Inside Macintosh, 
Volume III, pp. 205-209). 


If a divide or join operation fails, the incomplete files are not deleted. 


= Divided pieces of a file retain the type and creator of the composite file, so they 
can sull be opened by double-clicking from the Finder. The file piece probably 
won't make much sense to the application that created it. 
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= Unlike the original Divjoin, version 1.0d9 always divides to 3.5-inch disks. If you 
want the divided pieces of a file on the same hard disk, you must copy them there 
from the 3.5-inch disks after leaving Divjoin. 


2 The list of files for a divide operation sometimes omits files large enough to need 
dividing. For instance, a 781K file will not appear in the dialog box, even though 
it's too large to fit on a double-sided disk (which has 779K free after initialization). 


The only workaround at present is to divide to single-sided instead of double- 
sided disks. 
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This chapter describes the user interface of Smalltalk-80 for the Macintosh, and in 
particular the ways in which it varies from Xerox Version I. For a full discussion of 
the Xerox Smalltalk-80 user interface, see Smalltalk 80: The Interactive 
Programming Environment, by Adele Goldberg (listed in Appendix E, 
“Bibliography of Smalltalk Literature”). 











Scroll bars 


Just as in standard Macintosh applications, the full contents of a window or pane are 
usually not visible at any given time. Scroll bars are provided to select what portion 
will be displayed. These are similar in spirit to the standard Macintosh scroll bars, 
but there are some differences in operation. 


To operate a scroll bar, move the cursor into the window or pane you wish to scroll. 
After a short pause, the scroll bar will appear at the left side of the window. The gray 
marker inside the scroll bar indicates the position of the currently visible portion 
relative to the overall contents of the window. Unlike the standard Macintosh scroll 
box, however, the height of the marker within the whole scroll bar corresponds to the 
proportion of the window’s contents that are currently visible. 


To scroll, move the cursor to the left or right of the marker. It will change its shape to 
an arrow showing the direction in which the contents of the window will scroll when 
you click the mouse: up when the cursor is to the right of the marker, down when it's 
to the left. The vertical position of the cursor within the scroll bar controls the 
distance the window will scroll. Scrolling up moves the line of text directly opposite 
the cursor to the top of the window; scrolling down moves the current top line down 
to where the cursor is. If you press and he'd down the mouse button, the window will 
scroll continuously until you release the button or until it reaches the top or bottom 
of the window’s contents. 


If you move the cursor into the gray marker itself, it changes into a small black dot 
By pressing and holding down the mouse button at this point, you can drag the 
marker directly to the desired position, just as in a standard Macintosh scroll bar. As 
you drag the marker, a dotted oudine shows its original position, so that if you 
change your mind and want to cancel the scroll you can move it back to where it 
started before releasing the button. Directly above or below the marker, the cursor 
changes to a right-pointing arrow. Clicking at this point will jump the marker directly 
to the indicated position and scroll the contents of the window accordingly. 
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Pop-up menus 


Instead of the familiar Macintosh pull-down menus that run across a menu bar at the 
top of the screen, Smalltalk uses pop-up menus that appear right at the current cursor 
position when you press the mouse button. The particular menu you get depends on 
the area of the screen in which you press the button; you can also control the choice 
of a menu by holding down certain keys on the keyboard in combination with the 
mouse button. f 





The Xerox mouse buttons 


The original Xerox implementation of Smalltalk-80 was designed for a three-button 
mouse. The buttons, designated red, yellow, and blue, have the following functions: 





Button Function 





red Selects information within a window l 
yelow Displays a menu for operating on the contents of a window 
blue ` Displays a menu for operating on the window itself 


The Xerox three-button user interface is fully described in the Goldberg book, 
Smailtalk-80: The Interactive Programming Environment. In Smalltalk-80 for the 
Macintosh, other conventions are used to adapt this interface to the one-button 
Macintosh mouse. 


In general, the Macintosh mouse button corresponds to the red button on the Xerox 
mouse. You use this button to select text or list items within a window, to position 
windows when moving or resizing them, and so forth. Holding down the Option key 
while pressing the mouse button makes it behave like the Xerox yellow button; the 
Command key transforms it into the Xerox blue button. In addition, moving the 
cursor into certain areas of the screen makes it behave like the yellow or blue button 
instead of the red one: 


Near the right edge of any scroll bar, the mouse button works like the Xerox yellow 
button, displaying the pop-up menu specific to that window or pane. To signal this 
behavior, the cursor changes to look like a little menu. 
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In a windows tile tab, the mouse button works like the Xerox blue button, 
displaying a window menu for manipulating the window itself (moving, resizing, 
closing, and so forth) rather than its contents, 


(J 
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In thé grav background area outside of any window, the mouse button works like the 
Xerox yellow button, displaying a system menu of global commands applying to 
the system as a whole. 


Pop-up menus 


Notice that these conventions eliminate the need for the Option and Command keys 
in conjunction with the mouse: by moving into the proper areas of the screen, you 
can invoke all the functions of the Xerox red, yellow, and blue buttons via the single 
Macintosh mouse button. 


The system menu 


The system menu consists of global commands that apply to the system as a whole. 
To display it, press the mouse button anywhere in the gray background area of the 
screen, outside of all windows. The system menu contains the following commands: 


Command Action 


restore display Restores correct screen appearance; repaints all windows 


find window Brings a designated window to front of screen 

fast windows Enables fast redrawing of windows (see “New Features,” below) 
open project Opens a new project window 

open browser Opens a new system browser 

open workspace Opens a new workspace window 

open file list Opens a new file-list window 


open transcript Opens a new transcript window 


eject disk Ejects a disk 

exit project Exits to “parent” of current project 
snapshot Saves current state of system to disk 
quit Exits from Smalltalk 





The window menu 


The window menu contains commands for manipulating a window itself, rather 
than its contents. To display this menu, either press the mouse button in the 
windows utle tab, or press it anywhere within the window while holding down the 
Command key. The window menu contains the following commands: 
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Command Action 


label Edits title in windows tide tab 
move Changes window’s position but not its size 
frame Changes both window’s position and size, or restores 


a collapsed window to its original position and size 
collapse Shrinks window to just a title tab 


close Destroys window permanently 


Other menus 


In addition to the system and window menus, each type of window or pane has its own 
specialized menu for manipulating or operating on its contents. To dispiay this 
menu, either press the mouse button near the right edge of the scroll bar (when the 
cursor appears as a picture of a litle menu), or press it anywhere within the window or 
pane while hoiding down the Option key. The contents of these specialized menus 
vary, depending on what's appropriate for a particular window or pane. For 

instance, a workspace window presents the standard text-editing menu described in 
Chapter 3. 


Menu differences from Xerox Smailtalk-80 


The menus in this version of Smalltalk-80 for the Macintosh differ from those in 
Xerox Version II Smalltalk in the following ways: 








Menu Xetox command Macintosh command 

System project open project 
browser open browser 
workspace open workspace 
file list open file list 
transcript open transcript 
save snapshot 
(not supported) find window 
(not supported) fast windows 
(not supported) eject 

Browser, class categories spawn browse 
add category add item 
edit all reorganize 


Pop-up menus 
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Menu (continued). Xerox command Macintosh command 


Browser, class names spawn browse 
protocols reorganize (moved to message categories) 
spawn hierarchy (not supported) 

Browser, message categories spawn browse 

add protocol add item 

Browser, message selectors spawn | browse 
move (not supported) 
(not supported) versions 

Dictionary inspector . add field add key 


The goodie Version II Menus (described in Appendix B) will make the menus 
more compatible with those in Xerox Version Il. There are also significant 
differences in the pop-up menu for spelling correction; see Chapter 3 for further 
discussion. Í 











File lists 


This release of Smalltalk-80 for the Macintosh runs under the Hierarchical File 
System (HFS) of the Macintosh Plus, but does not yet have an iconic interface to 
represent files and folders. In place of the Macintosh Standard File dialogs, it uses an 
enhanced version of the Smalltalk file-list browser to access the files in an HFS folder 
hierarchy. 


To open a file list on your screen, use the open file list command on the 
system menu. The choose volume command in the top pane of the file-list window 
displays a menu of volumes and folders currently known to the system. Names 
followed by three dots (C...) denote a volume or folder that, in turn, contains 
subfolders of its own. When you choose one of these, you get a new menu showing the 
subfolders it contains. Choosing the same volume or folder twice in a row gives you a 
list of its files in the second pane of the file-list window. When you select any of these 
files, its contents appear in the bottom pane. You can then read the file’s contents or 
edit them and write them back out with the put command. The get command 
cancels any editing you may have done and reverts to the file’s original contents as 
read from the disk. 


Each time you use choose volume, the system will remember all the volumes or 
folders you select along the way and will display them in the top-level volume menu 
the next ume you use the command. This saves you the trouble of navigating back 
through the hierarchy the next time you want to access the same folder. However, 
such “remembered” folders are forgotten when you quit and restart the system, 


pari 
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unless they are referred to by some existing object in your saved image (such as an 
open file-list window). 


In addition to remembered folders, you may see the following names on your 
volume menu: 


Name Meaning 





Internal Internal 3.5-inch disk drive 

External External 3.5-inch disk drive 

Device3 Hard disk 

MacDefault Volume or folder from which Smalltalk was started up 


The file list always comes up initially displaying the last of these (the folder from 
which you originally started up Smalltalk from the Finder). 


New features 


Version 0.3 of Smalltalk-80 for the Macintosh includes a number of new user interface 
features. These fall into the following categories: 

Q faster drawing and manipulation of windows on the screen 

© enhancements to the browser 

T new text-editing features 

2 improved change management 


The first two categories are covered here; text editing is discussed in Chapter 3 and 
change management in Chapter 4. 





Fast windows 


Probably the most important change in this release is that Smalltalk now preserves 
the images of obscured windows and can therefore refresh them much more quickly. 
To change back and forth from one browser to another, which used to take about nine 
seconds, now takes about three. In addition, the screen is now properly updated and 
doesn't show the ugly gray “holes” characteristic of earlier releases. 


There are a couple of things to know about the new window management scheme. 
One is that the extra stored images consume memory space, and it is possible to 
exhaust the available space by creating too many large windows. The system will 
attempt to deal with this problem as gracefully as possible. If Smalltalk runs out of 
memory, it will first discard all its saved window images and revert to the old slower 
method of window management. It will also put up a notification window informing 
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you that it has done this. After you figure out what's wrong and make more memory 
available, you can choose the fast windows command from the system menu to 
re-enable fast window management. 


Executing (via the doIt or printIt command) a method that draws graphics on 
top of the current windows can cause confusing effects on the frontmost window. In 
such cases, you can use the Shift key together with the doIt or print It command; 
this saves the original screen image before executing the graphics method. After 
execution is complete, the resulting graphics will remain on the screen until you click 
the mouse button, at which point the entire screen will be redrawn, restoring all 
windows to their proper appearance. 


In connection with the new window management scheme, it is now possible to install 
graphic forms other than the default gray pattern as the screen background. For 
example, executing the statements 


QDPen new mandala: 30 diameter: 640. 
ScheduledControllers backgroundForm: 
(Form fromDisplay: Display boundingBox). 


will draw a geometric pattern on the screen, copy that pattern to a form, and then 
instali the form as the screen background. The background form consumes a certain 
space overhead, however: about 20K for the 512-by-342 Macintosh screen. To revert 
to the dull but space-saving gray pattern, execute 


ScheduiedControllers backgroundForm: (InfiniteForm with: Form Gray). 





Browser enhancements 


The new release includes the following enhancements to the system browser: 


a 


3 Anew versions command is available in the message selectors pane. This 
command opens a new browser showing all available prior versions of a selected 
method. You can revert to an earlier version of the method by selecting the 
desired version and choosing the accept command. This can be especially 
useful for rescinding unsuccessful changes you may have made. 


New commands in the class and message categories panes make it easier to add 
and rename categories. The rename command allows you to change the name of 
the currently selected category; add Item adds a new one. The new category is 
inserted just before the one currently selected, if any, if no category is selected, 
the new one is added at the end of the list 


ag 


= The rename command in the class names pane allows you to change the name of 
an existing class. A new browser is opened showing all methods that refer to the 
class by name, so you can update them to the new name. 
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= When you browse all methods that refer to some object or message (as with the 
senders command in the message selectors pane), each method appears with 
the first reference to the selected name automatically highlighted. This helps you 
locate the reference visually, and makes it easy to replace it with a different name 
or selector (as with paste or again). 


© If you make changes in a browser that have not yet been accepted, and then 
attempt any operation that would lose those changes, Smalltalk now highlights the 
affected pane and asks you whether to accept the changes before proceeding with 
the requested operation. Many operations which were awkward or confusing in the 
previous release have thus become simpler or clearer. 


New features 






Chapter 3 


Text Editing 


Smailltalk-80’s text-editing facilities are based on a cut-and-paste model similar to 
that used in other Macintosh applications. This implementation, Smalltalk-80 for the 
Macintosh, includes a number of additional features and modifications to make it 
even closer to the standard Macintosh model. These include, for example, using the 
Shift key to extend a selection and the keyboard combinations Command-x, 
Command-C, Command-v, and Command-2 for the standard editing operations 
cut, copy, paste, and undo. 


However, there are still some differences between Smalltalk's editing conventions 
and those of the standard Macintosh user interface. In Smalltalk, for example, you 
can type text into a window only when that window is active and contains the cursor. 
When the cursor is outside the active window (or pane), anything you type on the 
keyboard is saved for later insertion. As soon as you move the cursor back into the 
window, the text you typed will be inserted; but if instead you activate a different 
window by clicking inside it, the saved text will be inserted in that window instead. 


Another difference is the interpretation of double mouse clicks. Double-clicking 
within a word selects the word, just as under standard Macintosh conventions. In 
Smalltalk, however, double-clicking at the beginning or end of a line of text selects 
the entire line, and double-clicking just inside one of a pair of matched punctuation 
marks (such as parentheses, quotation marks, or square brackets) selects everything 
between the paired marks. (This feature is particularly useful in program text, for 
finding balanced parentheses and brackets.) For a complete description of the 
standard Smalltalk-80 editing features, see the Goldberg book, Smailtaik-80: The 
interactive Programming Environment. 











The editing menu 


The standard editing menu offered by workspace windows (and in modified form by 
other types of window as well) includes the following commands: 
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Command Action 


again Repeat last editing operation 

undo Undo last editing operation 

copy Copy selected text to scrap 

cut Cut selected text from wincow to scrap 

paste Paste scrap over current sc‘ection or at insertion point 
dott Execute selected text as Smalltalk code 


printit Execute selected text as Smalltalk code and display result 
accept Incorporate editing changes permanenty 
cancel Cancel all changes since last accept 


Typing from the keyboard doesn't disturb the contents of the cut-and-paste scrap 
buffer, which continues to hold the last text explicitly cut or copied from any window. 


Improved undo command 


The undo command has been overhauled for more Macintosh-like behavior. It now 
faithfully restores the text and selection to their condition before the last editing 
operation. All editing operations can now be undone (or redone by undoing the 
undo), even if you have since moved the selection. As a result, you can no longer use 
undo as a form of repeated paste. (Exception: When you are in a paragraph other 
than the one where you performed the original operation and there is no other way to 
get back the contents of the undo buffer, you can still get it back with undo.) The 
behavior of undo has been changed in the following ways: 


ni 


= Undoing a cut or copy restores the scrap buffer to its previous contents. Thus if 
you cut some text and then accidentally choose copy instead of paste, you can 
undo the copy and then complete the original paste. 


= Any sequence of typing and backspacing keys, however mixed, is treated as a 
single operation. An undo will restore everything that was deleted, and another 
undo will redo the original operation perfectly. 


= Undoing or redoing a cancel faithfully restores the earlier state. (Please forgive 
the excessive screen activity that accompanies this operation.) 


The editing menu 
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I Many more operations are now transparent to undo; that is, the previous 
operation can still be undone and redone. Besides scrolling, selecting, accept, 
and doIt, these now include 


G cut or copy of an empty selection 
O again when nothing was found 


© leaving the window or pane and returning without doing any further editing in 
other views 


Extended again command 


The again command has been extended in the following ways: 


Z Besides repeating the last paste or overtype at the next occurrence of the same 
Original text, again can now also repeat other operations that delete or replace 
text—-in particular, cut. 


O The again command no longer has any effect on the cut-and-paste scrap buffer. 
If you do some typing followed by again, and then want to paste the same text 
somewhere else, use copy to get the selected text into the scrap buffer for pasting. 


O Any sequence of typing and backspacing keys, however mixed, is treated as a 
single operation and can be repeated with again. (in previous versions of the 
system, you couldn’t use again after a type-in if you had backspaced to make a 
correction.) If you backspace past the beginning of the original selection, the 
characters you backspace over will all be included in the search string. 

The again command repeats the last replacement in any window or pane, not just 


the one that is currently active. (This currently doesn’t work right in “Senders 
of ...” windows.) 


0 


If you hold down the Shift key while choosing again, it will replace every 
occurrence of the search string to the end of the text, not just the next occurrence. 
Undoing a Shift-again restores the text and selection to their exact prior state 
(except for font), and you can redo. 


(3 


2 Undoing an unshifted again just resc 2s the text in the one place it was changed 
and leaves it highlighted. Redoing the again at this point (by undoing the undo) 
will repeat the replacement in that one place; explicitly choosing another again 
will leave it as is and instead replace the mext occurrence of the original search 
text. (This is because the again command always starts its search at the end of the 
current selection.) 


= In previous versions, if you wanted to search for something, you had to see an 
example of it, select the example, choose copy, then choose again. In this 
version, if you can’t see an example of the text you want to search for, you can 
place the insertion caret anywhere, type the search text, and choose again. The 
example you typed will automatically be deleted before beginning the search. The 
typing and deletion of the search text are transparent to the cancel command, 
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that is, if you’ve made no other changes to the text, you need not cancel before 
closing the window or browsing to a different method. 


If the last command was again (or an undo of an again), the same search and 
replacement strings are used as were used the last time. In the past, if you searched 
for text with again and then did some editing, you lost the ability to search for the 
next occurrence of the same text. You can now use the Command-S (same) 
command (see "New Keyboard Commands,” below) to continue the most recent 
again instead of repeating the intervening edit 


$] 


New keyboard commands 


The following new editing commands are available via Command-key combinations 
on the keyboard. (None of these commands except undo is available on a menu, but 
exchange will work correctly if you add it to the editing menu yourself.) 





Keystroke Command Action 

Command-Z undo Same as menu command undo 

Command-S same Repeat most recent again 

Command-L left Shift selected lines left 

Command-R right Shift selected lines right 

Command-D duplicate Paste current selection over previous selection 
Command-E exchange Exchange current selection with previous selection 
Command-Q query Complete symbol preceding caret 

Command-A advance Advance caret to next token 





Same (Command-$) 


Command-s (same) repeats the most recent search or replacement you performed 
with the menu command again. The new search begins at the end of the current 
selection. This allows you to do other editing in between again commands, then 
continue to search for more occurrences of the same text. This operation is 
transparent to undo and doesn't force a cancel. 
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Shift Left (Command-L) and Shift Right (Command-R) 


Command-L and Command-R shift text left and right by inserting and deleting tab 
characters at the beginning of each line. (A line of text is considered to be any 
sequence of characters delimited by carriage returns or by the beginning or end of 
the text) These commands operate on every line that includes at least one visible 
character of the current selection; lines containing only invisible formatting 
characters such as spaces and tabs are not affected. If the selection is an insertion 
caret, only the single line containing it is shifted. - 


Lines that don’t begin with a tab character cannot be shifted left. If the selection 
includes any such nonblank lines, Command-L will just flash the window and leave 
all selected lines unchanged. 


Duplicate (Command-D) 


Command-D (duplicate) pastes the current selection over the previous selection, but 
without affecting the scrap buffer. You can use this operation to copy existing text 
from somewhere else while typing from the keyboard. It’s also useful for copying 
temporary variable names from the body of a method to the declaration line at the 
beginning. 


To be considered a separate selection for purposes of Command-D, the current 
selection must not overlap the previous one (though it may touch it at either end). If 
the previous selection was an insertion caret, the new one must not enclose it or 
touch it at either end. Command-D leaves the caret positioned at the end of the 
duplicated text (that is, in the neighborhood of the previous selection). To select the 
duplicated txt, se Command-- (see “Other Keyboard Conventions,” below). 





Exchange (Command-E) 


Command-E (exchange) exchanges the current selection with the previous selection, 
without affecting the scrap buffer. Again, to be considered separate, the two 
selections must Lot overlap. Whatever text was selected before the exchange remains 
selected afterward, but in its new location (where the previous selection was 
originally). If both selections were nonempty, another Command-E is the same as 
an undo unless you have changed the selection in berween. 


One of the many uses for this command is to exchange the true and false branches of 
a conditional: double-click inside one of the brackets enclosing the first branch, 
then inside one of the brackets of the second, and type Command-E. Other 

common uses are to exchange two statements, two arguments of a message, or the left 
and right sides of a simple assignment. 
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Either the current or previous selection, but not both, may be empry Gust an 

insertion caret). In this case, Command-E performs a move instead of an exchange: _ 
the nonempty selection is moved to the location marked by the empty one. This 
operation is useful in the same situations as Command-D (above), but when you want 
to move the selected text instead of copying it. A caret is left at the end of the moved 
text; if you want to select the text, use Command-~ (see “Other Keyboard 
Conventions,” below). After a move, another Command-E is not the same as an 
undo; it just flashes the window and does nothing. 





query (Command-Q) 


Command-Q (query) saves typing by completing a partially typed message selector. 
The current selection must be empty (an insertion caret) and must be preceded 
immediately by an identifier, called the Aint. Smalltalk searches its symbol table for a 
selector that compietes the hint, and replaces the hint with this selector, called the 
offering. Notice that the symbol table is searched, not the method dictionaries. Only 
symbols that could be selectors and that begin with a lowercase letter are offered. The 
case (upper or lower) of characters in the hint does not matter, but spelling does. 


If the offering is a single-keyword selector, it is followed by a space and then the 
caret. For example, if you type desel and then Command-Q, Smalltalk will display 


deselect: a 


You can then proceed to type the argument following the selector. If the offering is a 
muiti-keyword selector, two spaces are inserted between each pair of keywords, and 
the caret is placed after the first keyword, allowing you to type in the first argument 
without touching the mouse. For example, if you type detec followed by Command- 
Q, Smalltalk will display 


detect: a ifNone: 


After typing the argument, you can use Command-A (see below) to advance to the 
next argument. 


If the offering displayed is not the one you want, type Command-Q again 
immediately. (The previous offering must still be displayed, and you must not have 
done any intervening editing.) Smalltalk will then search for another offering and 
substitute it for the first one. For example, if you type another Command-Q in the 
example above, Smalltaik-80 will display 


cetecti a 


When no further matches can be found, Command-Q will restore the original hint 
(before the first Command-Q) and flash the window. 


If you choose undo when an offering is displayed and no further editing has 
intervened, the original hint will be restored. Another undo (that is, a redo) will 
restore the state before the first undo, and you can continue the search. 
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If you type Command-Q and then click the mouse elsewhere in the text while an 
offering is displayed, another Command-Q will restore the previous selection and 
continue the search with the same hint. If only the original hint is displayed, the 
identifier before the new position of the caret becomes a new hint and a new search 
begins. 

Command-Q is useful when you can’t remember the spelling or capitalization of a 
long message selector, or when you can't remember all its keywords, or when you just 
don’t want to type a lot. It is particularly useful for long messages to the special object 
Mac (see Chapter 6), especially if you have taken the trouble to get their true keywords 
into the symbol table instead of a lot of with:’s. You can also use it when you're 
inventing a new message name and you want to be sure it is new, or conversely, if you 
want to try to pick a name that has been used before. 


Type as many characters of the name as you can remember, then type Command-Q. 
Usually you'll type the fisst keyword, including the colon; but if you wish, you can 
type fewer or more characters. All of the following will be completed to the selector 
detect :ifNone: 


detect: 
deT 
detect:lfn 


The more you type, the more ambiguity you will remove and the fewer spurious 
answers you'll receive. If you find yourself working through a long list of matches, 
choose undo (or type Command-z), add a few more characters to the hint, and type 
Command-Q again. 





Advance (Command-A) 


Command-A (advance) advances the caret to follow the next occurrence of the 
characters colon-space. You can use it after a Command-Q to advance to successive 
argument positions within a multi-keyword selector. For example, after Command-Q 
gives you the offering 


detect: a ifNone: 


type the first argument and then use Command-A to obtain 


aetect: firstArg ifNone: a 
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Other keyboard conventions 


Here are some other useful keyboard conventions: 


rr rrr "msm 





Keystroke Meaning 

Command-* Select last text typed in, pasted, duplicated, etc. (like Escape key in other 
Smalltalk systems) 

Command-~ Same as Command-~ above 

Command-_ Add or remove parentheses around selection (like Command-( in other Smalltalk 


systems; that combination is unavailable on the Macintosh because Command- 


Shift-9 is reserved for a different purpose) 
Shift-6 Up arrow (for returning method result) 


Shift-minus Left arrow (for assignment) 


Command-period Interrupt current operation immediately (like Control-C in other Smalltalk systems) 
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Spelling correction 


Spelling correction is automatic rather than voluntary in this version of Smalltalk-80 
for the Macintosh, and you have the opportunity to choose among the closest 
matches. When you accept a method or execute an expression with doIt or 
printit, Smailtalk compiles the code you've selected or accepted. When the 
compiler encounters a symbol it doesn’t recognize, it presents a menu of suggested 
alternatives, in case you've made a typing or spelling error. If you choose one of the 
alternatives, it will be substituted for the original misspelled version and compilation 
will proceed. 


If the misspelled symbol is a message selector, the menu includes, in addition to any 
proposed alternative spellings, 


= the text you originally typed (in case it is correct and you just haven’t yet defined 
the method in question) 


E} 


try harder (widen the search for possible alternatives; the original correction 
algorithm favors symbols that begin with the same letters) 


cancel (if you see your spelling error and want to fix it yourself) 


i) 


+ 


Note: Many valid Toolbox calls (see Chapter 6) are unknown to the compiler, 
so it may well be appropriate for you to accept the unrecognized selector as is. 
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If the misspelled symbol is a variable name beginning with a lowercase letter, the try 
harder command will be replaced on the menu by declare temp, to add this 
name to the method's list of temporary variables and proceed with the compilation. 
If the name begins with an uppercase letter, the command will be declare Class 
Variable instead. 


Miscellaneous 


The text editor in version 0.3 of Smalltalk-80 for the Macintosh also includes the 
following miscellaneous features and improvements: 


© When the selection is empty (an insertion caret), the cut and copy commands 
have no effect. They just flash the window, and don’t change the contents of the 
scrap buffer. They also don’t force a cancel if you've done no other editing. 


O When the selection is nonempty, the command sequences copy, copy-undo, 
and copy-again change the scrap buffer but don’t force a cancel. 


O Command-v (paste) may be typed ahead without flushing previously typed 
characters. This is useful when you want to type a few characters before pasting, or 
when you want to paste the same text in several places. The paste and the typing 
on either side of it are considered separate commands for purposes of undo. 


© In previous versions of the system, if you typed something and then clicked the 
mouse before all the typed characters had been processed, the editor gave 
priority to the mouse, made a new selection, and inserted the typeahead there. 
This version gives priority to the typeahead, so it will be inserted in the right place 
most of the time. 

Z The scroll bar marker (scroll box) no longer blinks after every edit and burst of 
typing. Typing and backspacing now adjust the marker if necessary. 


= If you try to invoke the format command (without the Shift key down) when you 
have already made some edits to 2 method, the window flashes. You should 
accept or cancel before trying again. Ct used to format the original text, causing 
your edits to vanish.) 
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Chapter 4 


Saving Your Work 
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As in any computer system, it is vitally important to back up all the work you do in 
Smalltalk. Keep in mind, though, that because Smalitalk (unlike other programming 
environments) makes no firm distinction between system and application code, it's 
possible to modify the system itself in such a way as to leave it unusable. It is thus 
equally important to make sure you have a healthy, working version of the system to 
fall back on in case your modifications should prove catastrophic. This chapter 
discusses a variety of tools that Smalltalk offers to aid you in saving your work and 
avoiding disaster. 











Images and snapshots 


Your image file and changes file (see Chapter 1) together define the compiete state of 
your Smalltalk system. The most straightforward way to back up your work is simply to 
save copies of these two files on external media. CYou might even want to keep a 
historical archive of different versions of the files through their various 

incarnations.) You can name the files anything you like, provided that the two names 
end in .image and .changes and are otherwise identical: for example, 
MySmalltalk-9/26.image and MySmalltalk-9/26.changes. If the files grow 
too large to keep on a single disk, you can use the DivJoin utility (see Chapter 1) to 
divide them for backup. 


As described in the next section, the changes file is maintained for you automatically 
by the Smalltalk system. Maintaining the image file is your responsibility. The 
snapshot command on the system menu saves a new version of the image file, 
recording the exact state of your working environment, down to the arrangement of 
windows on the screen and the current selection in the active window. The new 
snapshot is written out to the same image file you used when you started up Smalltalk 
from the Finder. 


Each tme you leave Smailtalk with the quit command, you're asked whether you 
want to save your changes since the last snapshot. If you answer yes, a snapshot of 
your Current state is saved to your image file before quitting, so that your next working 
session will begin exactly where this one left off. If you answer no, your working state 
at the start of the next session will revert to the previous snapshot. 
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In general, you should make a snapshot before undertaking any critical change that 
might damage or compromise your system. However, don't forget that the snapshot 
will replace the previous (presumably “safe") version of the image file that you 
already have on your disk. If you think you'll be making a snapshot, it’s a good idea to 
make a backup copy of your existing image and changes files in the Finder, before 
starting up Smalltalk. 


If you've made some changes that you want to save ina snapshot, but you forgot to 
back up your files in advance, ail is not lost. First file out the changes you wish to save 
(see “File-Out and File-In," below). Then quit to the Finder without saving changes, 
make backup copies of your image and changes files, and restart Smalltalk. Now you 
can file in your changes and safely make a snapshot. 











Changes and crash recovery 


As you work with Smalltalk, the changes file keeps a log of everything you do. Each 
time you compile a method with the accept command or execute an expression 
with doIt or printIt, a copy of the code is appended to the changes file in 
Smalltaik's standard file-out format (see “File-Out and File-In," below). This 
happens automatically, even if you don’t explicitly save a snapshot or file out your 
changes. If there is an unexpected system crash, you thus have a complete record in 
the changes file that you can use to reconstruct your work and restore the state of your 
system. 


If you crash and lose your work, select and execute the statement 
Smalltalk recover: 5000, 


in your System Workspace window. This will copy the last 5000 characters of the 
changes file to a temporary file named st 80.recent, and open an editing window 
on that file. (You can vary the number of characters as needed; the only limitation is 
that imposed by the file window, currently 16,000 characters.) You can now recreate 
your lost work by selecting the relevant information in this window and filing it back 
in. The file window’s menu command fileItIn operates only on the current 
selection, not the entire file. In the case of method definitions, the selection must 
include the methodsFor: line preceding the definition, as well as the exclamation 
points that delimic it at the end. Another way to examine and selectively file in code 
from the changes file is with a change-list browser, described below under “File-Out 
and File-In.” 


Changes and crash recovery 


33 


The changes file grows every time you run Smalltalk. If you redefine a method twenty 
times, there will be twenty copies of it in the changes file. This can be useful if you 
want to cancel your recent changes and revert to an earlier version of the method; 
the versions command in the browser's message selector pane allows you to 
browse all the earlier versions of a method. Even if you don't save changes when you 
quit Smalltalk, your changes file will have grown during the session. Eventually, you'll 
find it necessary to condense the changes file: that is, to write a new copy containing 
only the code accessible from the current image. To do this, execute the statement 


Smalltalk condenseChanges. 


in your System Workspace window. The condensing process can take time (ten 
minutes or more), depending on the size of the changes file. It's a good idea to make 
backup copies of your image and changes files before condensing and take a 
snapshot immediately afterward. i 


If you don’t have a hard disk, you must pay particular attention to the amount of free 
space on the disk you keep your changes on. The condensing process itself requires 
additional space for the condensed copy, so you should ideally condense the 
changes file before it becomes larger than the space remaining on the disk. If this 
becomes too restrictive (and if you're very brave), you can use the goodie 
DropChanges, described in Appendix D. This reclaims all disk space occupied by 
the changes file, but at the expense of losing all the source code the file contains. 
Future browsing of the affected methods will present only a decompiled version of 
the code; all variable names and comments will be lost Subsequent changes will 
continue to be logged in the changes file, allowing full source browsing until you drop 
changes again. If you must resort to this solution, you should probably first file out 
any code you care about, to retain a copy of the code with comments (see *File-Out 
and File-In," below). 


File-out and file-in 


You can save parts of your Smalltalk system to external files in Ale-out format; this 
provides a more compact way of saving selected changes than snapshot, which 
saves your entire image and all changes it contains. The £ileOut commands in the 
various panes of a browser window write all the code of a selected class category, 
class, method category, or method to a file, This code can later be read back in from 
a file-list or file window with the fileIn or fileItIn commands. File-out and file- 
in operations are also available by executing certain Smalltalk expressions; see your 
System Workspace window and Appendix A for examples. A detailed description of 
the file-out format is given in the article “The Smalltalk-80 Code File Format,” by 
Glenn Krasner, in Krasner's book Smailtaik-80: Bits of History, Words of 

Advice (see Appendix E, “Bibliography of Smalltalk Literature”). 


34 Saving Your Work 


File-out format allows code to be moved from one Smalltalk image to another and to 
be read or edited with any Macintosh text editor, such as the Macintosh 
Development System (MDS) Edit program or the Macintosh Programmer's 
Workshop (MPW) editor. You can also edit such files in MacWrite™ or Microsoft 
Word™, if you take care not to disturb the file-out format conventions. (However, 
yOu must remember to save the files in text-only form so they can later be read back 
into Smalltalk.) 


Note that browsers do not immediately reflect changes made in other browsers or in 
file-ins. It may be necessary to reselect an item in order to display the current 
version. The update command in the browser's class categories pane causes it to 
dispiay new system categories created by another browser or by a file-in. This 
command is the most reliable way to make sure the browser reflects the current state 
of the system. 











The change set and projects 


In addition to the changes file, Smalltalk provides another, completely independent 
mechanism for recording your changes. Whereas the changes file is a sequential log 

that records the text of all methods compiled and expressions executed, the change 

set is an unordered collection telling which classes and methods have been changed 
(added, deleted, modified, renamed, or reorganized). A statement of the form 


(FileStream newFileNamed: ‘MyChanges~9/26.st') fileOutChanges. 


will file out all classes and methods in the change set to the named file. You can then 
empty the change set, to begin collecting new changes, with the statement 


Smalltalk noChanges. 


Change sets combine with Smailtalk’s project mechanism to provide a convenient 
way of organizing and modularizing your file-outs. Each project window you open 
(via the open project command on the system menu) represents a separate 
working environment, with its own desktop, its own set of windows, and its own 
independent change set. By using a separate project window for each programming 
task, you can keep your changes separate and file each out in its own file. 


Here is a step-by-step procedure for using projects and change sets for modular 
program development: 


. Start with a relatively stable version of the system and back it up on a disk before you begin. 

. Start Smalltalk. 

. Open a new project window and enter it to start a new change set. 

. Isolate exacuy what makes up the programming change (new feature or bug fix) you wish to make. 


. Code the change, commenting extensively for future reference. 


ON vi A DI ON + 


. File out the change set for this project, using the Smalltalk statement shown above. 
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7. Quit Smalltalk and return to the Finder. 
8. If you wish, edit the file-out to add comments at the top describing its contents and purpose. 


9. Restart Smalltalk to test your file-out, using the backup copy as the original image that you made in 
step 1 above. 


10. File in the change. 

11. Test the change. 

12. Fix if necessary and file out the updated change. 

13. Make a snapshot to incorporate the change into your Smalltalk image. 


You can now give a copy of your file-out to someone else or file it into a different 
image. Use the select conflicts command in a change-list browser (see next 
section) to avoid code conflicts when porting a change from one image to another. 








Change-list browsers 


This version of the system includes a new type of browser, called a change Hst. It 
allows you to browse files in file-out format, by presenting one list item for each 
object in the file. This provides a way to examine file-out files that are too long for an 
ordinary file window, which is limited to 16,000 characters or less. The browser's list 
pane permits multiple selections, allowing selected parts of the file to be filed in or 
copied to another file. 


To create a change-list browser for a file, execute a statement of the form 
ChangeList browseFile: 'MyChanges-9/26.st'. 

One use for a change list is to browse the system changes file itself. The statement 
ChangeList browseRecentLog. 


in the System Workspace window opens a change list for browsing all changes since 
the last snapshot. This is useful for recovering changes after a fatal error or power 
failure. After restarting Smalltalk, you car pen a browser and file in all your unsaved 
changes (or, if you wish, only selected ones). 


It's also possible to browse farther back in the changes file than the last snapshot. To 
do this, execute a statement like 


cnangelList browseRecent: 12000. 


giving a large enough character count (say 10,000 or 20,000) to reach as far back as 
you want to go. This can be useful for selecting just certain desired changes from 
among others that are not of interest. You can then file out just those changes to a 
separate file and give them.to someone else to use. 
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The select conflicts command in the change-list browser’s list pane helps you 
detect code incompatibilities when filing in changes from several different files 
(perhaps developed independently by different people). After filing in each set of 
changes, you can open a change list on the next and choose select conflicts. 
This command selects every method definition in the given file that conflicts with 
one already included in the current system change set. You can then file in all but the 
conflicting methods, examine the conflicting ones, and try to resolve the conflicts in 
whatever way is appropriate, 
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The Hierarchical File 
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This chapter describes the new features in this release of Smalltalk-80 for the 
Macintosh that let it work with the Macintosh Plus Hierarchical File System (HFS). 


Volumes and folders 


Macintosh volumes are represented by Smalltalk objects of class HFSMacVolume, a 
subclass of FileDirectory. (Throughout this chapter, the word volume is 
understood to refer either to a physical volume such as a 3.5-inch or hard disk, or to 
a folder within the Hierarchical File System.) Any file name may be preceded by an 
optional volume prefix, separated from the file name by a colon: 


volumePrefix: fileName 


If the volume prefix is omitted, the file is understood to reside on the default volume. 
Initially the default volume is the one containing the image file from which Smalltalk 

was Started up; you can change it to a different volume by sending a message to class 

FileDirectory of the form 


FileDirectory default: ‘MyVolume', 
If you want no default volume to be defined at all, you can send the message 
FileDirectory noDefault. 


Notice that Smalitalk’s volume prefixes are only one level deep: they may 
not designate a fully-qualified pathname of arbitrary depth. To access a volume 
nested several levels deep in the folder hierarchy, you can use the special prefix 


n 


When Smalltalk encounters this prefix in a file name (or when the file name has no 
prefix and no default volume is currently defined), it displays a menu of volume 
names on the screen like that used by the choose volume command in a file-list 
browser (see Chapter 2). You can now proceed to navigate your way through the 
folder hierarchy to the desired volume in the same way as with the choose volume 
command. Just as in choose volume, the volume you designate, as well as all 
others you choose along the way, become known to the system and can thereafter be 
used as simple, one-level prefixes. In addition, removable 3.5-inch disk volumes 
become known to the system when they're inserted in a drive and remain known even 
if later ejected. 


40 The Hierarchicai File System 


You can define aliases for existing volume names by sending the message 
alias:to: to dass FileDirectory. For example, the statement 


FileDirectory alias: 'MyDisk* to: 'Internal', 


defines MyDisk: to be a valid volume prefix referring to the same volume as 
Internal. Once defined, an alias is completely equivalent to the original volume 
prefix. However, aliasing is not transitive: that is, after 


FileDirectory alias: '‘Blood' to: 'Sweat'. 
FileDirectory alias: 'Sweat' to: 'Tears', 


the prefix Blood: is not equivalent to Tears: and no longer equivalent to Sweat:. 
To cancel an alias definition, send a message of the form 


FileDirectory unalias: ‘MyDisk'. 


The following standard prefixes are built into the system: 





Prefix Meaning 

Internal Internal 3.5-inch disk drive 

External Externai 3.5-inch disk drive 

Device3 Hard disk 

MacDefault Volume or folder from which Smalltalk was started up 





(Notice that the name MacDefault is not the same as the default volume mentioned 
earlier. MacDefault always refers to the volume containing the Smalltalk image file, 
and is not affected by the FileDirectory default: message.) The volumes 
these refer to are known as fixed volumes and have some special properties. You 
may alias other names to these volumes or alias these names to other volumes, but 
the property of being a fixed volume belongs to the volume itself, not the prefix. 


Instances of class. HFSMacVolume respond to most of the standard Macintosh 
volume operations. In particular, the messages eject, flush, mount, and 
unmount are defined. CYou can also eject a disk by choosing eject disk from the 
system menu, then selecting the volume you want to eject from the pop-up menu that 
appears.) Ejecting merely places the volume off-line but doesn’t unmount it, so files 
may still be open on an ejected disk. On shutdown, all volumes are flushed and all 
open files are closed and placed in a state such that further activity on them will fail. 
Files will be reopened when the system comes up (if still referenced), but no check 
will be made to see if it is really the same volume. 


For compaubility with the abstract Smalltalk model, open and close are also 
defined in class HFSMacVolume, and are equivalent to the standard Macintosh 
operations Get VolInfo and FlushVol, respectively. Smalltalk tries to keep you 
from wreaking havoc on the Macintosh's file system, but is far from foolproof. For 
instance, it's possible to unmount the Macintosh startup volume from within 
Smalltalk, with predictably disastrous results. 


Volumes and folders 








Files 


Macintosh files are represented by objects of class HFSMacFileStream This is a 
subclass of FileStream, the standard Smalltalk class denoting a file. Instances of 
HFSMacFileSt ream respond to the standard Smalltalk protocol for streams and 
files, as well as to other messages specific to Macintosh files, such as finderInfo, 
setFileInfo:, and isVisible. For a full discussion of streams and files, see 
Chapter 12 of Smailtalk-80: The Language and its Implementation, by Goldberg 
and Robson (listed in Appendix E). 


To open a file, send a message to class FileStreamof the form 
FileStream fileNamed: ‘Hello' 


This will open an existing file of the given name if there is one, otherwise create a new 
one. You can include a volume prefix if you wish, or omit it to open a file on the 
default volume. To limit the operation to an already existing fe, use 


FileStream oldFileNamed: ‘Hello’ 


This will open a notifier if no such file exists, asking permission to create a new one. 
Similarly, you can use 


FileStream newFileNamed: ‘Hello’ 


to insist on a new file. If a file already exists by this name, a novifier will be opened’ 
asking for permission to overwrite it. Any time you do overwrite an existing file, you 
must remember to send it the message shorten before closing it, otherwise part of 
the old data may remain after the end of the new contents. 


By default, all files created by Smalitalk have file type TEXT. This allows them to be 
read by any text editor that can handle text-only files, such as “MDS Edit, the MPW 
editor, MacWrite, or Microsoft Word. They are automatically given MacWrite’s 
creator signature, so that they will run MacWrite when dout! --clicked in the Finder. 
You can give a file a different type and creator, if you wish, bv sending it the message 
setType:creator:. 
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Chapter 6 


Accessing the Macintosh 
Toolbox : 


An important feature in this version of Smalltalk-80 for the Macintosh is its 
programming interface to the Macintosh User Interface Toolbox and Operating 
System. Smalltalk programs can call any routine in the Macintosh ROM: that is, any 
routine that is accessed using a trap. (Routines that are not accessed through traps are 
not currently supported.) To support this capability, this version of Smalltalk 
includes mechanisms for calling the ROM routines themselves and for manipulating 
the Pascal-style records and other data objects that these routines use. Most of the 
support code for Toolbox access is contained within the Smalltalk class categories 
ToolBox-Support, ToolBox-Structures, and ToolBox-Heap Access. For 
detailed information on the ROM routines themselves, see Apple’s comprehensive 
Inside Macintosh manual. 





Pascal data structures 


Pascal-style data objects for use with the Toolbox are allocated directly from the 
Macintosh application heap, rather than from Smalltalk's own internal heap. When 
Smalltalk is first started up, it expands the application heap to its maximum size, 
reserves a fixed amount (normally 36K) for Toolbox objects, and allocates the rest as 
one large, nonrelocatable block for its own use. Within this private heap, Smalltalk 
allocates all of its normal (Smalltalk-style) objects and does its own memory 
management and garbage collection, independent of the Toolbox Memory 
Manager. Pascal-style objects are allocated in the remaining portion of the 
application heap and are accessed indirectly from within Smalltalk via “proxy” 
objects in the Smalltaik heap itself. 
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The Smalitaik classes that support access to Pascal-style data structures are 
summarized in the following subclass hierarchy: 


Object (} 
PascaiRecord ('handle' ‘pointer' 'bits') 
HeapObject () 

HeapArray ('logicalSize'} 
EightInts (} 
EightLongs () 
Pattern ({) 

HeapRecord (} 
BitMap () 
Finfo () 
GrafPort () 

HeapRecordPointers ('pointerArray') 
HParamBlockRec () 

Picture (} 
Region () 
$t255 () 


PascalRecord, HeapObject, HeapArray, HeapRecord, and 
HeapRecordPointers are defined in category ToolBox-Heap Access. All the 
rest—the classes representing actual Toolbox data structures such as Pattern, 
GrafPort, and HParamBlockRec—are in ToolBox-Structures. 


The root of this hierarchy of classes is PascalRecord, which has three fields named 
handle, pointer, and bits. At any given time, at most one of these fields should 
be non-nil, depending on the nature of the object represented: 


~ 


3 Ifhandle ~= nil, it holds a SmallInteger or LargePositiveInteger that. 
is a handle (the address of a master pointer) to a relocatable block in the 
application heap. 


= Ifpointer ~= nil, it holds a Smallinteger or LargePositiveInteger 
that is the address of a nonrelocatable block in the application heap. 


= Ifbits ~= nil, it holds a ByteArray that is the direct representation of the 
object's value. 


= Ifhandle = pointer = bits = nil, the PascalRecord refers to no object 
at all. 


For objects that reside in the Macintosh heap (handle ~= nilor pointer ~= 
nil), you must explicitly send the object the message release when you're through 
with it; this in turn calls the Toolbox trap DisposHandle or DisposPtr to 
deallocate the object from the heap. release is not called for you during garbage 
collection, so the pointer or handle in an object is lost if the object is garbage- 
collected before you send release. The space the object occupies in the Macintosh 
heap becomes unrecoverable for the remainder of your Smalltalk session. 
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Defining record types 


Class HeapObject defines standard protocol for its subclasses HeapRecord and 
HeapArray. All Smalltalk classes representing Pascal record types are subclasses of 
HeapRecord. To define a new record class, send 2 message to class HeapRecord of 
the form 


HeapRecord recordSubclass: #NewClassName 
fields: 'fieldi field2 ...' 
types: 'typel type2 ...' 
category: ‘ToolBox-Structures' 


Where fieldil, field2,... are the names of the record’s fields and typel, 
type2,... designate the corresponding data types. Each type specification is 
either a one-character code representing a primitive type or the name of another 
HeapObject subclass (for an embedded record or array). The following table shows 
the code characters for the primitive types; embedded subrecords are discussed in a 
separate section below. 


Character Paseal type Smailtaik type 


I INTEGER SmallInteger, LargePositiveInteger up to 16 bits 
L LONGINT Smallinteger, LargePositiveInteger up to 32 bits 
B BOOLEAN Boolean 

P Point Point 

R Rect Rectangle 

S Str255 String 

DI: Ptr PascalRecord (D for “direct pointer”) 

H Handle PascalRecord 


Methods will automatically be defined in the new subclass for accessing and changing 
all of the fields you name in your definition message. These methods use Smalltalk's 
built-in primitive 161, which takes rwo arguments: a byte offset within the record and 
a one-character suing designating the type of value to be found there. For example, 
class GrafPort includes the following methods for accessing the portRect field of 
the GrafPort record: 


portRect 
<primitive: 161 recordOffset: 16 type: 'R'> 
Tseif primitivefailed 

portRect: rect 
“primitive: 16i recordOffset: 16 type: 'R'> 


Tselé pramitiveFailed 
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The recordoffset value of 16 tells the primitive that the desired field begins at an 
offset of 16 bytes from the start of the record; the type string 'R' tells it that the 
value contained in that field is a rectangle. (The primitive can distinguish berween 
the two messages by the number of arguments it receives on the stack.) The 
primitive: 161 part in these definitions is optional: the methods could just read 


portRact 
<recordOffset: 16 type: 'R'> 
self primitiveFailed 


portRect: rect 
<recordOffset: 16 type: ‘R'> 
Tselt primitiveFailed 


instead. 


If you select a HeapRecord subclass in the browser’s class names pane and hold 
down the Shift key while choosing the definition command, a template will 
appear in the code pane showing the names and types of the record’s Pascal-style 
fields. 


% Note: Never hold the Shift key down while filing out a class. 


Subrecords 


When a Pascal-style record contains embedded subrecords or other data structures 
(such as the BitMap record embedded in the portBits field of a GrafPort), the 
problem of accessing these fields is less straightforward than for the simple data types 
listed in the table above. Ideally, when you ask for the contents of such a field, you 
should get back a new object that refers to the same data as in the Original record 
(wherever it resides), so that garbage collection works reasonably and changes to the 
subrecord are properly reflected in the parent record. 


That's just what happens with objects that reside in the Macintosh heap. A new 
instance of class PascalRecord is created, with its pointer field set to point to the 
desired subrecord at the appropriate offset within the parent record. You can then 
use this object to access or change the contents of the subrecord just as if it were a 
separate object. 


There are risks to this approach, however. If the parent record is subsequently 
deallocated or moved within the Macintosh heap, your pointer to the subrecord will 
become invalid. Furthermore, you can sabotage the Toolbox Memory Manager if 
you try to treat the subrecord as if it were an independently allocated object. If you 
send the subrecord object the message release, for instance, the Toolbox trap 
DisposPtr will be called with a value that points into the middle of a heap block 
instead of the beginning, and a system error will result 
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In general, rather than keep around a subrecord object that points into the middle of 
the parent record, it’s better to create 2 new instance of the subrecord and copy the 
original data to it. In fact, for records residing in the Smalltalk heap, that’s what you 
get in the first place. Again, a new instance of PascalRecord is created, but with a 
copy of the data instead of a pointer into the middie of the original record. In this 
case, changes to the subrecord are not reflected in the parent record. If you want to 
set a field of a subrecord, you have to get the subrecord with the appropriate access 
method, set the field, then store the modified subrecord back into the parent record. 


For example, suppose pbRec is an instance of class HParamBlockRec, representing 
a parameter block for use with the Toolbox File Manager. Field ioFlFndrInfo is a 
subrecord of the parameter block, of type Finfo, holding the file’s Finder 
information. If you want to set the fdCreator field of the Finfo record, you can't 
do it with a straightforward message such as 


poRec ioFlFndrInfo fdCreator: ‘MACA’. 


because the object returned by pbRec ioFlFndrInfo is a copy of the Finfo 
subrecord, not a reference to the embedded subrecord itself. So to set the 
fdCreator field, you have to do it in a more roundabout way: 


finderInfo « pbRec ioFlFndrInfo. 
finderInfo fdCreator: ‘MACA’. 
pbRec ioFlFndrinfo: finderInfo. 


Currently, class HParamBlockRec is the only one that allocates its data on the 
Smalltalk heap. HParamBlockRec is a subclass of HeapRecordPointers, which is 
used to pass the addresses of buffers and other data objects that exist in the Smalltalk 
heap but are pointed to by fields of a Toolbox record structure. If Smalltalk’s memory 
manager moves such an object within the Smalltalk heap, the pointer in the Toolbox 
structure will be left pointing to the wrong address. HeapRecordPointers avoids 
this problem by substituting the correct addresses of such objects at the time of the 
Toolbox call, within the low-level primitive that implements the call. 


For example, suppose one of the fields of the Pascal record fooRecord is a pointer 
to a Smalltalk byte array named fooBuffer. You would use an object of class 
HeapRecorcPointers with a pointer array whose first element is the offset of that 
field within fooRecord, and whose secv.id element refers to the object fooBuffer 
itself. During the call in which fooRecord is passed to the Toolbox as a parameter, 
the primitive will calculate the current address of fooBuffer in the Smalltalk heap 
and store it at the specified offset in the record before passing the record to the 


Toolbox. Thus the Toolbox is guaranteed to get the correct address of fooBuffer at 
the time of the call. 


Class HeapRecordPointers is tricky to use and skimpily documented, and you 
should avoid it if at all possible. If you absolutely must use it, be sure to study it 
carefully beforehand, and be forewarned. 
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Heap inspectors 


A handy new feature in this release is class HeapInspector, which allows you to 
open a Smalltalk-type inspector window on any object that belongs to a subclass of 
HeapRecord. You can now examine and modify all the fields of a Pascal record in 
the same way you can for a standard Smalltalk object. Just send the message inspect 
to any object belonging to a HeapRecord subclass. 


Heap inspectors use the list of field names and field types stored in each heap 
object’s class variables to access the individual fields of the record and display their 
names. Class HeapRecord uses the same lists in its subclass definition method 
(recordSubclass: fields:types:category:), to compute the offsets of all 
fields and automatically generate methods for accessing and setting them. 











Calling the Toolbox 


In general, you issue calls to the Macintosh Toolbox by sending messages to the 
Smalltaik object Mac, the only instance of class Macintosh (defined in category 
ToolBox-Support). The first keyword of the message selector corresponds to the 
name of the Toolbox routine as given in Inside Macintosh, but beginning with a 
lowercase letter. For example, for the Toolbox routine defined in Pascal as 


PROCEDURE FrameRect (r: Rect); 

a Pascal call such as 

FrameRect (myRect) 

would correspond to the Smalltalk message 
Mac frameRect: myRect. 


If the Toolbox routine has more than one parameter, the second and subsequent 
parameters are converted into keywords in the Smalltalk message: for the Pascal 
routine 


PROCEDURE FrameRoundRect (r: Reet; ovalWidth, ovalHieight: INTEGER); 
the Pascal call 

FramercundRect [(myRect, w, h) 

converts to the Smalltalk message 


Mac frameRoundRect: myRect ovalWidth: w ovalHeight: h. 
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A Toolbox routine that takes no parameters at all corresponds to a unary message in 
Smalltalk: to call the Pascal routine 


PROCEDURE HidePen; 
you would use the Smalltalk message 


Mac hidePen. 





Primitive 160 

Calls to the Toolbox are implemented via two interpreter primitives, numbers 160 
and 162. The first, primitive 160, takes two parameters: an integer (usually expressed 
in hexadecimal form) representing the last three digits of the Toolbox trap word, and 
a coded string of characters describing the arguments to the Toolbox routine. For 


example, the Toolbox routine FrameRect, whose Pascal declaration was given 
earlier as 


PROCEDURE FrameRect (r: Rect); 
is defined in Smalltalk, in class Macintosh, as follows: 


frameRect: r 
<primitive: 160 trapA: 16rCAl type: '+-R'> 
Tself primitiveFailed 


Here the trapA parameter gives the last three hexadecimal digits of the trap word; 
the first digit is always understood to be A, so the compiete trap word, in Pascal 
notation, is $ACA1. The type parameter is coded according to conventions that 
we'll be discussing in a minute; in this case, it specifies that the routine has one 
argument of Pascal type Rect and returns no function result. The primitive will check 
the type of the argument passed on the Smalltalk stack and signal failure if it doesn’t 
match. Otherwise it will convert the value to Pascal format, push it onto the 
Macintosh stack, and call the designated trap. 


The type parameter to primitive 160 is a string containing a sequence of individual 
type specifiers. Each specifier consists of one of the eight code letters representing 
the primitive data types (I, L, B, P, R, S, D, or H), as shown in the table above under 
“Defining Data Types.” This type letter may optionally be preceded by a V, denoting 
a VAR parameter. For parameters passed in registers rather than on the stack, the 
type letter is followed by a digit specifying the register. The Toolbox uses three 
registers for parameter passing, denoted by the following code digits: 


Digit Register 


0 DO 
1 Al 
2 AQ 
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Thus the type specifier VLO would represent a VAR parameter of type LONGINT, 
passed in register DO. In the string passed as the type parameter to primitive 160, the 
first type specifier represents the function result returned by the Toolbox routine (or 
~ for procedures that don’t return a result); the second denotes the Smailtalk object 
to which the message is sent (or ~ if the message receiver is not a parameter of the 
Toolbox routine); and the rest of the string gives the types of the remaining 
parameters. Some more examples shoula help make all this clear: 


Pascal 


PROCEDURE GetPort (VAR gp: GrafPt.); 
Smalitaik 
getPort: gp 

<primitive: 160 

trapA: 16rc74 "trap word = $AC74" 


type: '--VD'> "no result, ignore receiver, VAR pointer" 
Tselt primitiveFailed 


Pascal 
PROCEDURE OpenPort (gp: GrafPtr); 


Smalltalk 


openPort: gp 
<primitive: 160 
trapA: 16rc6r "trap word = SACEF" 
type: '--D'> "no result, ignore receiver, pointer” 
Tseif primitiveFailed 
Pascai 


FUNCTION SectRect (srcRectA, sreRectB: Rect; VAR dstRect: Rect) 


BOOLEAN; 
Smalltalk 
sectRect: srcRectA srcRectB: sarcRectB dstRect: datRect 
<primitive: 160 
trapA: LErcCAA “trap word = SACAA" 
type: 'BeRRVR'> "Boolean result, ignore receiver, 


A rectangie, rectangle, VAR rectangle" 
seit primitiveFailed 
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Pascal 
FUNCTION NewPtr (logicalSize: Size): Ptr; 
Smalltalk 


newPtr: logicalSize 
<primitive: 160 
trapA: 16r01E “trap word = SAOQ1LE" 
‘type: 'D2-L0'> "pointer result in AC, ignore rece‘ ver, 


long intager in DO" 
Îself primitiveFailed 


Pascal 
PROCEDURE SetPt (VAR pt: Point; h,v: INTEGER); 
Smalitalk 


setPt: pt h: hv: v 
<primitive: 160 
trapA: 16rC80 "trap word = SAC80" 
type: ‘--VPII'> "no result, ignore receiver, 
VAR point, integer, integer" 
Tself primitiveFailed 


Instead of defining this last method in class Macintosh, it could instead be put in 
class Point. Instead of 


Mac setPt: thePoint h: horiz v: vert 
you would write 
thePoint setH: horiz v: vert 


In this case the message receiver itself is one of the arguments to be passed to the 
Toolbox routine, so the method definition in class Point would be 


aatE: h vi v 
<primitive: 160 
trap: 16rc89 "trap word = SAC80" 
type: '-VBII'> “no result, receiver is VAR point, 
integer, integer" 
Tsels primitiveFailed 


As with primitive 161, the primitive: 160 in all these definitions may be omitted. 
For example, the last method could have been written as 


seti: h vi v 
<trapA: 16rC80 type: '-VPII'> 
A h è : ‘ E$ 
iseif primitiveFailed 
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Primitive 162 

If you browse class Macintosh, you'll find that most of the messages corresponding 
to Toolbox calls are not explicitly defined there. Instead, Macintosh redefines the 
message doesNot Understand: (which normally displays 2 notifier on the screen 
reading Message not understood) to intercept all unrecognized messages and 
pass them to another Smalitalk primitive, number 162. Instead of taking explicit 
parameters for the trap word and parameter types, this primitive looks up the 
undefined message selector in an internal table of Toolbox traps. (This search uses 
only the first eight characters of the selector and ignores upper- and lowercase 
differences.) If it finds an entry for this selector, it gets the appropriate trap number 
and parameter information from the table and completes the call; if not, it posts a 
notifier on the screen. 


Calling a Toolbox routine with primitive 162 takes longer than with primitive 160, 
because of the table lookup. However, the explicit method definitions needed to use 
primitive 160 use up space within your Smalltalk image. For this reason, it’s 
recommended that you use primitive 162 for most Toolbox calls, and 160 only for 
those that you use very frequently or for which speed is important, such as on-screen 
graphics. You can also use primitive 160 to define methods for new routines recently 
added to the Toolbox in the Macintosh Plus ROM. (In fact, because the Toolbox 
lookup table was not updated for this release, this is how all the new HFS file system 
calls were added to the system.) 


Another use for primitive 160 is to fix bugs in the internal lookup table used by 
primitive 162. If an attempted Toolbox call causes a primitive failure or a system 
crash, there’s probably something wrong with one of the parameters you passed to it. 
(Remember, for instance, that VAR parameters have to be preinitialized to 
something valid before being passed to the Toolbox.) However, it’s also possible 
that the call you’re trying to use is missing or encoded wrong in the lookup table; not 
all of the Toolbox calls were exhaustively tested before this release of the system was 
shipped. In this case, you can correct the problem by adding an explicit method for 
the trap using primitive 160. 


For example, the table entry for the Toolbox routine GetNextEvent is known to be 
incorrect. This routine, defined in Pascal.as 


FUNCTION GetNextEvent (eventMask: INTEGER; 
VAR theEvent: EventRecord) : BOOLEAN: 


is incorrectly encoded in the lookup table as B- IVD; it should actually be B- ID, 
since theEvent is declared as an event record, not a pointer to a record. (Under 
Pascal conventions, a pointer to the event record is passed on the stack, but the 
routine only changes the contents of the record, not the value of the pointer.) This 
error could be corrected (though it isn't in the actual release) by defining the 
following method in class Macintosh: 


Calling the Toolbox 


53 


getNextEvent: aventMask theEvent: theEvent 
<primitive: 160 
trapA: 16rD70 "trap word = $AD70" 
type: ‘B-ID'> "Boolean result, ignore receiver, 
integer, pointer" 
Tselt primitivefailed 











Things to watch out for 


Here are a few potential pitfalls to keep in mind when using the Toolbox from 
Smalltalk: 


o You'll probably need access to various Toolbox globals and constants. Methods 
for some of these are defined in class Macintosh in the message category 
globals/constants; those that aren't defined there are available with the 
StdPools goodie, described in Appendix B. Also look at category memory 
inspect in class Macintosh to see how to access or set specific memory 
locations from within Smalltalk. 


O Calls to Toolbox routines that return VAR parameters can sometimes lead to subtle 
problems when translated into Smalltalk. For example, the Pascal statement 


GlobalToLocal (theEvent.where) 
corresponds to the Smalltalk expression 
Mac globalToLocal: theEvent where. 


In this case, the where field of event record theEvent will never get the value 
returned to it, since the message theEvent where returns a temporary object 
that receives the new value returned to it. The correct way to code this is 


tempPoint e theEvent where. 
Mac glepaiToLocal: tempPoint. 
theEvent where: tempPoint. 


(} 


When using data in the Smalltalk/Toc’box environment, you must not pass the 
Toolbox the address (pointer or handle) of any data stored in the Smalltalk heap if 
the Toolbox is going to remember the address after returning from that one call. 
Although the location of a Smalltalk ByteArray object can’t change during the 
time a single Toolbox call is running, it is possible for it to change between calls. 
So byte arrays should be used only for data whose address is passed to the Toolbox 
again every time the Toolbox uses it. This ensures that the correct address will be 
used each time. 


C) 


In Smalltalk you can't write new values into a procedure’s parameters, as you can in 
Pascal. Instead you must create a local temporary variabie, along with the code to 

copy the parameter's value into that temporary. Within the method, you can then 

assign the new value to the temporary. 


54 Accessing the Macintosh Toolbox 


Z Toolbox routine names that are defined in Primitive 162’s lookup table may not be 
known to the spelling checker. The first time you try to use such a name as a 
message selector, the spelling checker will reject it and offer you a list of 
alternative spellings. When this happens, just accept the spelling as is; the spelling 
checker will then remember it and accept it without protest the next time you use it 


Things to watch cut for 55 














Appendix A 


System Workspace Summary 


Here is a summary of useful Smalltalk expressions that are available in the System 
Workspace window: i 











Changes and Files 
Smalltalk noChanges. Resets the change set to empty. 


Smalltalk condenseChanges. Condenses the changes file, removing 
multiple copies of method definitions, 
methods no longer accessible from the 
current image, and other unnecessary text. 
May take a long time, and requires sufficient 
disk space for two copies of the changes file. 
It's advisable to make backup copies of your 

` image and changes before condensing and 
take a snapshot immediately afterward. 


DispiayScreen removeFromChanges. Removes all changes in a given class from 
the change set. 


Y 


Smalltalk changes asSortedCollection 
Returns a sorted list of the current contents 
of the change set i 


Smalltalk browseChangedMessages. Opens a message browser on all methods 
in the change set 
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(FileStream fileNamed: '‘Changes.st') fileCutChanges. 
Files out all changes in the change set toa 
given file. 


(FileStream fileNamed: 'PenChanges.st') fileOutChangesFor: Pen. 
Files out all changes in the change set for a 
given class. 


{FileStream éèldFileNamed: ‘BrowseFeatures3.st') fileIn. 
Files in changes from a given file. 


(FileStream fileNamed: ‘’Hello') edit. 
Opens a file editing window on a given file. 


FileDirectory filesMatching: '*.st' 
Returns a list of all filenames matching a 
given pattern. (Actually, it's more 
convenient to open a file-list window and 
type the pattern into the top pane, followed 
by Return.) 


ChangeList browseFile: '‘changes.st'. 


Opens a change-list browser on a given file. 











ChangeList browseRecentLog. Opens a change-list browser on all changes 
in the system changes file since the last 
snapshot. 

Inquiry 

InputState browseAllAccessesTo: ‘deltaTime', 


Opens a browser on all references in.a class 
to a given instance variable. (Like inst 
var refs in the system browser.) 


Smalltaix browseAllCallsOn: r. Opens a browser on all calls to a given 
message selector. (Like senders in the 
system browser.) 


Smalltalx browseAllImplementorsOf:; #remove:. 
Opens a browser on all method definitions 
for a given message selector. (Like 
implementors in the system browser.) 
Smalltaix porowseAliCallsOn: (Smalltalk associationAt: #ShutDownList). 
Opens a browser on all references to a given 
global variable. 
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Smalltalk browseAllCalisOn: 
{Cursor classPool associationAt: #ReadCursor)., 
Opens a browser on all references in a class 
to a given class variable. 2 


Smalltalk browseAllCallsOn: (Undeclared associationAt: &#Disk}. 
Opens a browser on all references to a given 
undeclared variable. 


Smalitalk browseAllMethodsInCategory: #examples. 
Opens a browser on all methods in a given 
message category. (May cover more than 
one class.) 


{Smalltaik collectPointersTo: StrikeFont somelnstance) inspect, 
Opens an inspector on all objects that point 
to an instance of a given class. 











Smalltalk garbageCollect. Forces a full garbage collection of the 
Smalltalk heap. 

FileStream instanceCount Returns the number of instances of a given 
class currently in existence. 

FormView allinstances inspect. Opens an inspector on all instances of a 
given class. 

HouseCleaning 

Undeclared Dictionary new. Resets the dictionary of undeclared 


variables to empty. Note that you will no 
longer be abie to find the methods in which 


they occur. 
Undeclared inspect. Opens an inspector on all undeclared 
variables. 
endeciared associationsDo: 
[:assn | Smalltalk browseAllCallsOn: assn]. 
Browses all references to undeclared 
variables. 


i(Sbiect classPool at: #DependentsFields) keys 


Retums a set of all objects with dependents. 


HouseCleaning 
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(Object classPool at: #Dependentsfields) keysDo: 
[:each | (each isKindOf: DisplayText) 
ifTrue: [each release]. 


Releases all objects that satisfy a given 


condition. 

Transcript clear. Resets the transcript window to empty. 

Smalltalk forgetDolts. Removes methods generated by doIt and 
printIt. 

Symbol rehash. Purges any symbols that are no longer in 
use. 


Smalltalk removeKey: #GlobalName. 
Removes a symbol from the global 
dictionary. You should check first that there 
are no outstanding references to it 


Smalitalk declare: #GlobalName from: Undeclared. 
Declares a symbol as a new global variable. 
If it was formerly in the Undeclared 
dictionary, all references to it will now refer 
to the new global variable. (This is how 
forward references are handled in file-ins.) 











Globals 


Names in Smailtaix other than Classes and Pools: 
Display -- a DisplayScreen 
Processor -- a ProcessorScheduler 
ScheduledControllers -- a ControlManager 
Sensor -- an InputSensor 
Transcript -- a TextCollec* cr 
ScurceFlles -~ an Array of FileStreams 
SystemOrganization -- a SystemOrganizer 
StartUpList -- an OrderedCollection 
ShutDownList -- an OrderedCollection 


S 
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Variable Pcols (Dictionaries) 
Smailtalk 
Undeclared 
FilePool 
OSInt fPool 
BitMaskPool 
TextConstants 











System Files 


Sourcefiles « Array 
with: (FileStream oldFileNamed: 
Smalltalk sourcesName) readOnly 
with: (FileStream oldFileNamed: 
Smalltalk changesName). 
Establishes the sources and changes files. 


(ScurceFiles at: 1) close. Closes the sources file. 
(SourceFiles at: 2) close. Closes the changes file. 
SourceFiles « Array new: 2. Disables the sources and changes files. 


(Sources can still be retrieved with the 
goodie RetrieveSources.) 








Measurements 

Smalltalk spaceleft Returns the amount of free heap space 
currently available. 

Symbol instanceCount Returns the number of instances of a given 
class currendy in existence. 

Time millisecondsToRun: (Smalltalk allCallsOn: #asOop] 
Returns the time needed to execute a given 
block. 

MessageTally spyOn: (Smailtalx aliCallsOn: #as0op). 
Presents a time-use profile for execution of 
a given block. 


Crash recovery 


6} 











Crash recovery 


Smalltalk recover: 5000, 


Opens a window on the last 5000 characters 
in the changes file. 
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Smalltalk Goodies 


Included as samples with this release are several additional source files, known as 
goodies, which add interesting or useful capabilities to your Smalltalk system. The 
goodies are divided into two categories, demos and utilities, and are found in the 
folders Goodies-Demos, on Smalltalk Disk 2, and Goodies-Utilities, on 
Smalltalk Disk 7. 


To read a goodie named Gumdrop into your system, execute the statement 
(FileStream oldFileNamed: ‘Gumdrop.st') fileIn. 


or select Gumdrop. st ina file list window and choose fileIn from the list pane 
menu. The filenames are not case-sensitive, but spaces are significant. The .st 
extension is only a convention, to make it easy to browse all Smalltaik files using the 
pattern *.st in the top pane of a file-list window. 











Demos. 


The following goodies are found in the Goodies-Demos folder on Smalltalk Disk 2: 





Fractal 


Produces three-dimensional surfaces based on fractal geometry. For an example, 
execute 


Fractal example. 
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Toothpaste 


Allows you to draw shaded worm-like curves on the screen, using a “brush” that looks 
like a highlighted sphere. Execute 


Form toothpaste: 30. 


and then paint with the cursor. To stop, hold down the Option key and click the 
mouse. 


Web 


Another drawing program, which lags behind the current mouse position and then 
draws lines between the lagging cursor and the current cursor. Execute 


gQDPen new web. 


and then draw with the mouse. Click the mouse tc erase the screen, Option-click to 
stop. | 


Music 


A music synthesizer that drives the Macintosh four-tone sound generator. See the 
MacWrite file Music Docs in the Goodies-Demos folder on Smalltalk Disk 2 for 
more information. 








Utilities 
The following goodies are found in the Goodies-Utilities folder on Smalltalk 
Disk 7: 





Printing 


Defines a new class MacPrint Stream to support hard-copy printing on an Apple 
imagewriter™ printer connected to the printer port. Adds a menu command for 
printing in most windows. The method examples in MacPrintStream class 
gives general instructions for use. Printing from the window menu (in a window’s tile 
tab) produces a bit image of the window; printing from a text pane produces text, 
with an attempt to support the unusual Smalltalk characters. Also included is a 
method for rotating bit images by 90 degrees, for use if you want to implement 
landscape printing. 
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FFT 


Defines a new class FFT for performing a one-dimensional fast Fourier transform on 
data held in Smalltalk arrays. The example method test illustrates its use. This code 
computes a complex Fourier transform, a corresponding power spectrum can be 
derived by summing the squares of corresponding real and imaginary components. 


Macintosh-QuickDraw 


A full set of QuickDraw call definitions using primitive 160 instead of 162 (see Chapter 
6). This makes all the QuickDraw messages visible and easier to browse, at some cost 
in memory space. 





MacPaint 


Defines a method macPaintOn: in class Form to create a graphics file readable by 
MacPaint™, The comment at the end of the method gives a sample invocation. This 
method is already included in the released image and source, but its example 
comment is in error; this goodie corrects the comment. 





RS232 


Defines methods to support input and output via the two Macintosh serial ports. One 
of these includes a large comment explaining how to set baud rate and so forth; 
another is a sample application that downloads text (for example, from a laptop 
computer) to a Macintosh file. 





RetrieveSources 


Allows access to the full system source code, even without a hard disk. If you have 
browsed to a given method (decompiled) and wish to see the full source code (as you 
would with a hard disk), choose retrieve from the code pane menu. You will be 
asked to insert one of the disks containing the divided sources file, and then the full 
code will appear. This technique will fail if you happen to choose one of the three 
methods that straddle breaks between the file divisions. 
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DropChanges 


For the fearless programmer whose changes file has grown too large (even after 
condensing), but who still wants to continue making changes. Simply deleting the 
changes file would prevent the further recording of changes. Instead, by executing 
Smalltalk dropChanges, you can discard the current contents of the changes file 
(save them first, if you care), but the file will continue to record further development. 





StdPools 


Creates pools ToolInt£Pool, PackIntfPool, and QuickdrawPool, and adds to 
the existing OSInt fPool, so that all four match the latest Pascal interface files 
released with the Macintosh Programmers Workshop (version B2). These pools add 
approximately 10K to the size of your Smalltalk image. 





VersionilMenus 


This goodie makes the menus in version 0.3 more compatible with the menus in 
Xerox Smalltalk, Version I. It is especially useful if you are using any of the 
introductory books. 
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Memory Management 
Techniques 


The interpreter furnished with this release uses garbage collection rather than 
reference counts to reclaim unused storage. For this reason, it is not necessary to 
break circular structures in this implemettation, though such “release” code still 
exists in many parts of the system. You'll notice occasional pauses when garbage 
collection takes place. Still, the system’s performance is considerably better with 
garbage collection than with reference counting. A side effect of incremental garbage 
collection is that allInstances and related enumeration messages will sometimes 
enumerate objects that are no longer truly accessible. If you want to be sure of 
accurate results, execute 


Smalltalk garbageCollect. 
in the System Workspace immediately before such enumeration. 


Even with garbage collection, it is still possible to run out of memory. When space 
starts getting low (below about 1000 objets and 8000 words of data), Smalltalk 
attempts to gain some more by turning off fast window display. If there is enough 
space to do so, it will open a notifier window at this point to warn you that you're 
running out of space. It is generally advisable to close the notifier rather than 
proceed, since soft error recovery may not be possible. (If you get more than one 
such noufier, keep on closing them until you get no more.) 
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You can find out how much memory you have left with the expression 
Smalitalk spaceLeft 


in your System Workspace window. This returns the number of free objects and the 
number of free words of data. (The amount of space reported will generally be 
greater than at the time Smalltalk detected it was running low, because some extra 
space will have been gained by turning off fast windows.) For more specific, detailed 
information, use 


Smalltalk printSpaceAnalysis. 


This writes out a disk file names STspace.text, listing the approximate number of 
objects and words used by each class in the system. 


The activation stack displayed in the low-space notifier will show whether the 
problem was caused by endless recursion. If not, you should consider how else you 
might have unintentionally consumed a lot of memory and what steps you can take to 
free some. The problem may have been caused by having too many windows open 
on the screen, or something in your code may be using a lot of space. If you really 
need to make more space available in the system, here are some things you can try: 


O Execute 


Smalltalk deleteClasses. 


which will remove some of the less important classes and other objects from the 
system. (You may want to look at this method first, in class SystemDictionary, 
to be sure you want to remove all these classes. Also note that the current release 
doesn't include class SystemTracer, so remove the reference to this class from 
the deleteClasses method before executing it.) 


9 Remove the debuggers step and send commands, and any other code ihar uses 
the simulation in class ContextPart. If you can't live without step and send, 
then implement breakpoints (a useful thing to do anyway) and use these to restore 
the operation of step and send. 


O Make MessageSet, and maybe even Debugger, a subclass of Browser so that 
they can share code for printing, file-out, senders, and messages. 
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If you have a hard disk, remove class Decompiler. One minor problem is that 
the decompiler is currently used for viewing the code of doIt methods from the 
debugger. If you can't live without this, figure out how to log the text of doIt 
methods in the changes file and give them a proper source-code pointer. 
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After removing significant parts of the system in this way, you can execute the 
statement 


Smalltalk _removeUnSentMessages. 


This locates and removes any messages that are implemented but never sent from 
anywhere in the system. Its useful to run this method four or five times in a row, 
because each method removed may render other methods inaccessible. The 
method takes significant time (from 5 to 25 minutes) to run. 


Q Finally, you should execute 


Symbol rehash. 


which will reclaim all symbols that are no longer in use as a result of the removal of 
methods. 


Leaving more space for the Toolbox 


As mentioned in Chapter 6, the Smalltalk interpreter allocates most of the 
application heap as a single nonrelocatable block, which it uses for its own Smalltalk 
heap. The amount of space withheld from this block for Toolbox operations is 
determined by a resource of type STOP (for "Smalltalk options”) in the interpreter’s 
resource file, and is initially set to 36K. If you need more heap space for Toolbox 
objects and can spare it from your Smalltalk image, you can use the ResEdit resource 
editor to change this value. 


The STOP resource includes four values of 4 bytes each, only the first two of which are 
relevant and alterable. The first is the amount of heap space set aside for Toolbox 
operations, normally 36K; the second is the amount of stack space, normally 12K. 
Note that you're taking a chance if you change these values. If your Smalltalk image is 
already large and you reserve more space for the Toolbox or stack, the interpreter 
may not have enought free space to run the image the next time you try to launch it 


Leaving more space for the Toolbox 
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Known Bugs and Limitations 


The following is a list of known bugs and limitations in release 0.3 of Smalltalk-80 for 
the Macintosh. Please report any other problems you may encounter, using the bug 
report form at the end of this book. 


a 


The (collapsed) system browser on the initial startup screen of this release is not 
correctly updated. Selecting class PascalRecord in the class names pane will 
cause an error, since this class has been moved to a different category. To correct 
the problem, choose update in the browsers class categories pane. 


Method deleteClasses in class SystemDictionary still refers to class 
SystemTracer, even though this class has been removed from the system. The 
reference to SystemTracer should be deleted from the first statement of this 
method. 


Level 0 images from older versions (release 0.2) of Smalltalk-80 for the Macintosh 
won't run with the new interpreter. Level 1 images will run, but you should keep the 
0.2 interpreter around to run with level 0 images. You will also need to keep 
around two versions of the Smalltalk-80.sources file, since the 0.3 sources 
are new. To make sure both versions use the right sources, put the old sources in 
the root directory of your hard disk and the new ones in 2 folder along with your 
0.3 interpreter and image. 


If you move your Smallta\k image to a system with a larger display, existing 
windows cannot be framed larger than the old screen. If you can recreate the 
window’s contents easily, close and reopen it. 


For historical reasons, Smalltalk uses a few bytes of memory preceding its display 
object, the screen, for private purposes. But on the Macintosh, memory just 
below the screen may be used by other programs (MacsBug, the RAM cache, 
some file servers), and some of the new large screens have no memory there at all. 
To work around this problem, Smalltalk-80 for the Macintosh reserves the top scan 
line of the screen for its private use, and fools QuickDraw into thinking that the 
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screen is one pixel shorter than its tue height, starting at the second scan line 
instead of the first. You cannot access the top line, nor can you change the few bits 
of it that are left white. 


The system transcript window is not always updated correctly after the message 
Transcript clear. Reframing the transcript window corrects it. 


The choose volume command in a file-list window sometimes doesn’t correctly 
restore the area underneath the volume list. 


The find window command on the system menu has display problems if you 
select a window that's entirely or almost entirely off the screen Once you choose 
the window from the find window menu and position it on the screen, you can 
correct it by reframing. 


The form editor is buggy. 


Filename patterns containing an asterisk (*) should be used only in the top pane of 
a file-list window. Don’t use such patterns when specifying a filename from within 
a method. 


The explain command in the browser's code pane sometimes displays two 
Statements for you to execute, but omits the period between them. Insert a period 
before attempting to execute both statements with doIt. 


If Smalltalk crashes and leaves the changes file (or some other file) open, you may 
get an error when you try to restart Smalltalk, since the file can’t be opened a 
second time for write access. This doesn’t normally happen; but if it does, restart 
the entire system with the Finders Shut Down command before restarting 
Smalitalk. 


Holding down the mouse button during a snapshot may cause the system to return 
from the snapshot with the mouse out of sync. 


The system may occasionally hang during a large file-in. If this happens to you, 
restart Smalltalk and start the file-in over again. If you’re filing in many files at 
once, try filing each one in separately and doing a snapshot after each. 


If you start up Smalltalk under older versions of the Finder and system file, it may 
not open the sources and changes files properly. One indication of this problem 
would be decompiled instead of fully commented source code in the browser. If 
you encounter this problem, first make sure the file Smalltalk-80.sources is 
either in the root directory of your hard disk or in the same folder as your image 
file. If it is, try starting Smalltalk and immediately quitting and saving changes. If 
the problem persists, check the version numbers of the Finder and System file and 
make sure you're using at least versions 5.3 and 3.2 respectively. If not, use the 
Installer utility to install the newer versions from the system folder on Smailtalk 
Disk 1, then try another quit-with-save, followed by a restart. If your system 
sources are still inaccessible, please report the problem on the bug report form at 
the back of this book. 


Known Bugs and Limitations 


= There are some known bugs (and there may be others not yet discovered) in the 
internal table used by primitive 162 to call Macintosh Toolbox routines (see 
Chapter 6). 
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Bibliography of Smalltalk 


Literature 


Following is a bibliography of available lineranare on Smalltalk and object-oriented 
programming: 











introductory 


Goldberg, Adele. Smalltalk-80: The Interactive Programming Environment. 
Reading, Mass.: Addison-Wesley, 1984. Describes the user interface of Smalltalk, 
such as browsers and debugging tools. Sometimes referred to as the “orange book.” 
This book and the one below by Goldberg and Robson together offer a 
comprehensive description of Smalltalk-80. 


Kaehler, Ted and Patterson, Dave. A Taste of Smailtalk. New York, N.Y.: W. W. 
Norton & Co., 1986. A friendly introduction to the subject, including a detailed 
treatment of an actual programming problem. Points out differences between 
Smalitalk-80 Version I (Macintosh) and Version II (Xerox). 


Note: If you are using either of these introductory books, you may want to use 
the goodie VersionIIMenus described in Appendix B; it makes the menus 
more compatible with Xerox Version IL 
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Advanced 


Goldberg, Adele and Robson, David. Smalltalk-80: The Language and Its 
Implementation. Reading, Mass.: Addison-Wesley, 1983. Describes the Smalltalk 
language and system classes, with many examples. Sometimes referred to as the 
“blue book.” A companion volume to the book by Goldberg listed above. 


Krasner, Glenn, ed. Smalltalk-80: Bits of History, Words of Advice. Reading, 
Mass.: Addison-Wesley, 1983. A collection of papers describing several 
implementations of Smalltalk on different computers. For implementors of Smalltalk 
systems, not users. Sometimes referred to as the “green book.” 


Doyle, Ken; Haynes, Barry; Lentczner, Mark; Rosenstein, Larry. “An Object- 
Oriented Approach to Macintosh Application Development.” Paper presented at 
the 3rd Working Session on Object-Oriented Languages, Paris, France, January 8-10, 
1986. Describes the advantages of object-oriented programming for application 
development on the Macintosh. Gives the relationship betweeen Smalltalk, Object 
Pascal, and MacApp. : 








General interest 
BYTE Magazine, August 1981. This entire issue is devoted to Smalltalk. 


BYTE Magazine, August 1986. This entire issue is devoted to object-oriented 
languages, and includes a condensed version of A Taste of Smalltalk, by Kaehier 
and Patterson (see above). 


Schmucker, Kurt J. Object-Oriented Programming for the Macintosh. Hasbrouck 
Heights, N.J.: Hayden Book Company, 1986. Contains an entire chapter devoted to 
Smalltalk-80 for the Macintosh. 


“Smalltalk Comes to the Micro.” Computer Language Magazine, August 1985. 
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Smalltalk-80™ for the Macintosh™ 
Bug Report Form 


Smalltalk-80 is a trademark of Xerox Corporation. Macintosh is a trademark of Apple Computer, Inc. 
Return to: The Smalltalk Group (MS 22-Y) 

Apple Computer, Inc. 

20525 Mariani Ave. 

Cupertino, CA 95014 


AppleLink: Smalltalk Group care of SARDI1 
UNIX: ...lapple!smalltalk 


Reported by: Name Corman 


Address State Zip 





Phone 


Date 


System: Macintosh Plus Macintosh XL ___ Other 





Memory 

Disk Drives: Internal (400K/800K)___ «External (400K/800K) 
Apple Hard Disk 20 Apple Hard Disk 20SC 
Other (please specify) 


Other 
Peripherals: 


Describe any hardware 
upgrades/modifications: 


ROM Version: L System file Version: Finder Version: 
Smalltalk Version Number: 


What other software (debugger, RAM disk, etc.), if any, was 
running? 








Is the problem reproducible? 


Describe the problem (specific steps/examples) 











Smalltaik-80™ for the Macintosh 
Institutional License Agreement 


This Agreement covers an institutional license for Smalltalk-80. Please check which type of License 
you are applying for, fill in the number of machines for your institution, and sign this Agreement. 
Return this Agreement with the appropriate fee to: 


Apple Computer, Inc. 

20525 Mariani Avenue, M/S 28B 
Cupertino, CA 95014 

Attn: Software Licensing Department 


License Fee Check One 
Institutional license to make copies for a limited number 

of machines $150.00 La 
Special rate for educational institutions l $ 50.00 "+ 
Institutional license 


You have ordered an institutional license to use Smalltalk-80 for the Macintosh, version 0.2 and/or 
version 0.3 (hereinafter “system”) on machines within your institution. 





Apple grants to you the right to make that many copies of the system for distribution and use within 


your institution. You agree that the system shall only be distributed and used within your institution, 


and that the system will be used only in conjunction with the Macintosh Smalltalk interpreter, and 
running on Apple computer equipment 


You have read and agreed to the conditions stated above. 


Name: 


(piease print) 


Signed: CD ate: 


Co./University: 


= 


Address: 


City/State/Zip: 


Smalltalk-80 is a trademark of the Xerox Corporation. i 
Macintosh is a trademark of Apple Computer, Inc. 10/12/86 








